白山的技术手记Gitea Wiki

Gitea Wiki

Gitea Docker 部署与排障技术文档

由 Markdown 技术文档生成的 wiki 页面。公开版已对敏感服务器信息做占位符脱敏。

返回技术导航 返回首页文章
Source: Gitea-Docker-Yum-部署与排障技术文档.md

1. 背景

本文记录在 yum 系 Linux 服务器上使用 Docker 部署 Gitea 的过程，并整理本次遇到的问题与处理方法。

当前采用方案：

  • Gitea 运行在 Docker 容器中
  • 数据库使用 SQLite3
  • 暂时使用服务器 IP 访问
  • 暂不使用域名和 HTTPS，等待备案完成后再切换

服务器信息：

text
Gitea 服务器 IP：<服务器公网 IP>
Gitea Web 端口：<Gitea Web 端口>
Gitea SSH 映射端口：<Gitea SSH 端口>
访问地址：http://<服务器公网 IP>:<Gitea Web 端口>/

2. Docker 部署 Gitea

2.1 创建目录

bash
mkdir -p <Gitea compose 目录>
cd <Gitea compose 目录>

2.2 docker-compose.yml 示例

yaml
networks:
  gitea:
    external: false

volumes:
  gitea-data:
    driver: local

services:
  server:
    image: docker.gitea.com/gitea:1.26.4
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__server__SSH_PORT=<Gitea SSH 端口>
    restart: always
    networks:
      - gitea
    volumes:
      - gitea-data:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "<Gitea Web 端口>:<Gitea Web 端口>"
      - "<Gitea SSH 端口>:22"

2.3 启动服务

bash
cd <Gitea compose 目录>
docker compose up -d

2.4 检查状态

bash
docker compose ps
curl -I http://127.0.0.1:<Gitea Web 端口>

正常结果示例：

text
gitea Up
HTTP/1.1 200 OK

3. Gitea 初始化配置

初始化页面中建议使用：

text
Database Type：SQLite3
Path：<Gitea 数据库文件>
Repository Root Path：<Gitea 仓库目录>
Git LFS Root Path：<Gitea LFS 目录>
Run As Username：git
Server Domain：<服务器公网 IP>
SSH Server Port：<Gitea SSH 端口>
Gitea HTTP Listen Port：<Gitea Web 端口>
Gitea Base URL：http://<服务器公网 IP>:<Gitea Web 端口>/
Log Path：<Gitea 日志目录>

管理员账号可在初始化页面的 Administrator Account Settings 中创建。

4. 改回 IP 访问

如果初始化时填过域名，需要修改 Gitea 配置文件。

4.1 编辑 app.ini

bash
docker exec -it gitea vi <Gitea app.ini>

找到 [server] 段，改为：

ini
[server]
PROTOCOL = http
DOMAIN = <服务器公网 IP>
ROOT_URL = http://<服务器公网 IP>:<Gitea Web 端口>/
HTTP_PORT = <Gitea Web 端口>
SSH_DOMAIN = <服务器公网 IP>
SSH_PORT = <Gitea SSH 端口>

保存后重启：

bash
cd <Gitea compose 目录>
docker compose restart

然后访问：

text
http://<服务器公网 IP>:<Gitea Web 端口>/

5. 阿里云安全组

使用 IP 访问时，需要在阿里云安全组放行：

text
TCP <Gitea Web 端口>：Gitea Web 访问
TCP <Gitea SSH 端口>：Gitea SSH 克隆/推送

如果服务器系统防火墙启用了 firewalld，也需要放行：

bash
firewall-cmd --permanent --add-port=<Gitea Web 端口>/tcp
firewall-cmd --permanent --add-port=<Gitea SSH 端口>/tcp
firewall-cmd --reload

6. 域名与备案问题

本次尝试使用：

text
https://<Gitea 域名>/

但由于阿里云服务器接入未备案域名时会被拦截，页面提示：

text
域名暂时无法访问
该域名当前备案状态不符合访问要求

因此当前先回退到 IP 访问。

后续如果备案完成，可以再切换为域名访问。届时需要：

  1. 在 DNS 平台添加 A 记录：
text
主机记录：git
记录类型：A
记录值：<服务器公网 IP>
  1. 修改 Gitea 的 app.ini：
ini
[server]
DOMAIN = <Gitea 域名>
ROOT_URL = https://<Gitea 域名>/
SSH_DOMAIN = <Gitea 域名>
SSH_PORT = <Gitea SSH 端口>
  1. 配置 Nginx 反向代理。
  2. 使用 certbot 申请 HTTPS 证书。

7. Nginx 与 HTTPS 注意事项

如果证书尚未申请成功，不要提前在 Nginx 中写：

nginx
ssl_certificate /etc/letsencrypt/live/xxx/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/xxx/privkey.pem;

否则会出现：

text
cannot load certificate ".../fullchain.pem": No such file or directory

正确流程是：

  1. 先配置 HTTP 反向代理。
  2. 确认 http://域名/ 能访问。
  3. 再执行：
bash
certbot --nginx -d 域名
  1. 由 certbot 自动生成 HTTPS 配置。

临时 HTTP 反向代理示例：

nginx
server {
    listen 80;
    server_name <Gitea 域名>;

    client_max_body_size 512M;

    location / {
        proxy_pass http://127.0.0.1:<Gitea Web 端口>;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

8. Git 远程地址配置

8.1 查看远程仓库

bash
git remote -v

8.2 设置为 Gitea HTTP 地址

示例：

bash
git remote set-url gitea http://<服务器公网 IP>:<Gitea Web 端口>/<用户名>/<仓库名>.git

如果没有 gitea 这个 remote：

bash
git remote add gitea http://<服务器公网 IP>:<Gitea Web 端口>/<用户名>/<仓库名>.git

8.3 推送

bash
git push -u gitea master

如果默认分支是 main：

bash
git push -u gitea main

9. Git push 代理问题

本次出现错误：

text
Failed to connect to <服务器公网 IP> port <Gitea Web 端口> via 127.0.0.1

关键点是：

text
via 127.0.0.1

这通常说明本机 Git 正在走本地代理，但代理没有正常转发。

9.1 查看 Git 代理

Windows 终端中执行：

cmd
git config --list --show-origin | findstr /i proxy

9.2 清除 Git 代理

cmd
git config --global --unset-all http.proxy
git config --global --unset-all https.proxy

如果提示没有该配置，可以忽略。

9.3 清除当前终端代理环境变量

cmd
set HTTP_PROXY=
set HTTPS_PROXY=
set ALL_PROXY=
set http_proxy=
set https_proxy=
set all_proxy=

9.4 测试直连

cmd
curl.exe --noproxy "*" -I http://<服务器公网 IP>:<Gitea Web 端口>/

正常返回 200 或 302 后，再推送：

cmd
git push -u gitea master

也可以单次绕过代理：

cmd
git -c http.proxy= -c https.proxy= push -u gitea master

10. 常用维护命令

10.1 查看容器状态

bash
cd <Gitea compose 目录>
docker compose ps

10.2 查看日志

bash
cd <Gitea compose 目录>
docker compose logs -f

10.3 重启 Gitea

bash
cd <Gitea compose 目录>
docker compose restart

10.4 停止 Gitea

bash
cd <Gitea compose 目录>
docker compose down

10.5 启动 Gitea

bash
cd <Gitea compose 目录>
docker compose up -d

11. 后续建议

当前 IP 访问可用后，建议后续逐步处理：

  1. 完成域名备案。
  2. 切换为 https://<Gitea 域名>/。
  3. 使用 Nginx 反向代理。
  4. 申请 HTTPS 证书。
  5. 将 Docker 的 <Gitea Web 端口> 端口限制为本机访问，避免绕过 Nginx。
  6. 定期备份 Gitea 数据卷。

12. 当前推荐访问方式

现阶段推荐使用：

text
http://<服务器公网 IP>:<Gitea Web 端口>/

HTTP 克隆地址示例：

text
http://<服务器公网 IP>:<Gitea Web 端口>/<用户名>/<仓库名>.git

SSH 克隆地址示例：

text
ssh://git@<服务器公网 IP>:<Gitea SSH 端口>/<用户名>/<仓库名>.git