The deploy clone fetches from /srv/gitea/git/repositories/... which the job container cannot see, so 'git fetch' failed with exit 128. Mount it read-only and whitelist it.
Gitea + PostgreSQL(Docker Compose)
用 docker compose 运维 TJHLP 答疑平台的 Gitea 与 PostgreSQL。
本文档是唯一的部署与运维手册, 覆盖 部署 / 备份 / 恢复 / 升级 四条主流程。
┌──────────────────────────────────────────┐
学生/助教 ──https──▶│ Apache httpd (宿主机, 已有) │
│ ProxyPass /QA → 127.0.0.1:2080 │
└───────────────┬──────────────────────────┘
│ 只绑回环
┌───────────────▼──────────────────────────┐
│ docker compose 项目 "gitea" │
│ │
│ gitea (docker.gitea.com/gitea:1.27.3) │
│ │ /data ← ${GITEA_DATA_DIR} │
│ │ │
│ db (postgres:18.6 + zh_CN locale) │
│ /var/lib/postgresql │
│ ← ${POSTGRES_DATA_DIR} │
│ (PG18 实际数据在 18/docker/) │
└──────────────────────────────────────────┘
PostgreSQL 只在 compose 内部网络暴露, 不发布到宿主机
0. 快速索引
| 我要做什么 | 节 | 命令 |
|---|---|---|
| 在新主机上从零部署 | §4 | 见 §4 |
| 看状态 / 日志 / 重启 | §8 | docker compose ps · logs |
| 备份 | §5 | sudo ./scripts/backup.sh --quiesce |
| 恢复(含演练) | §6 | sudo ./scripts/restore.sh <时间戳> --apply |
| 升级 Gitea / PostgreSQL | §7 | 备份 → 改 .env → up -d |
| 改首页 / 中文术语 / 去 Gitea 化 | ../customization/README.md |
python3 customization/build.py → docker compose restart gitea |
| main 推送后自动部署(方案) | ci-cd.md |
Gitea Actions + 宿主 act_runner(host 模式) |
| 出问题了 | §12 | — |
| 退回二进制部署 | §9 | docker compose down && sudo systemctl start gitea |
三条铁律:
- 任何升级 / 迁移 / 改动前先备份 ——
sudo ./scripts/backup.sh --quiesce。 - 没演练过的备份不算备份 —— 定期照 §6 在测试机上恢复一次。
- 配置只改
compose.yaml与.env, 不要手工编辑容器里的app.ini(它是启动时按 env 生成的派生产物, 下次重建就被覆盖)。
1. 关键设计决策
| 决策 | 理由 |
|---|---|
版本全部锁定 (GITEA_VERSION, POSTGRES_VERSION) |
可复现、升级/回滚是改一行 .env |
Gitea 只发布 127.0.0.1:2080 |
Apache 反代配置无需改动; 同时消除"直连 2080 绕过 TLS"的暴露面 |
| PostgreSQL 不发布端口 | 只走 compose 内部网络; 外部无法直连数据库 |
配置全部用 GITEA__section__KEY 环境变量 |
官方镜像支持的机制; 不把宿主绝对路径写进 app.ini |
| 数据用 bind mount 而非 named volume | 备份/检查/回滚路径明确, 源数据可直接比对 |
自建 db 镜像补 zh_CN.UTF-8 |
官方 postgres 镜像只生成 en_US.UTF-8, 而现有集群 collation 是 zh_CN.UTF-8 |
| 关闭容器内 Gitea SSH | 现有部署的 git 用户没有 .ssh/authorized_keys, SSH 实际未使用 |
db 挂到 /var/lib/postgresql(而非 .../data) |
postgres:18 把 PGDATA 改成 /var/lib/postgresql/18/docker, VOLUME 也上移了一层 |
两个服务都 restart: unless-stopped |
开机自动恢复, 不依赖宿主的 gitea unit |
2. 已知陷阱(本机踩过的坑, 改配置前先读)
⚠️ 1. postgres:18 的挂载点。 若沿用 18 之前的老写法把数据目录挂到
/var/lib/postgresql/data, 容器不会启动, 入口脚本会打印there appears to be PostgreSQL data in: /var/lib/postgresql/data (unused mount/volume)然后exit 1—— 它通过mountpoint加/proc/self/mountinfo把该路径判定为 "未被使用的挂载点"。正确做法是挂父目录/var/lib/postgresql, 数据落在${POSTGRES_DATA_DIR}/18/docker。这个新布局的用意是让将来pg_upgrade --link不撞上挂载点边界。
⚠️ 2. s6
setup的 chown 守卫 —— 会让 Gitea 以[F]崩溃。 镜像里的/etc/s6/gitea/setup以 root 身份、在 Gitea 启动之前运行:if [ ! -d /data/git/.ssh ]; then mkdir -p /data/git/.ssh; fi # ← 以 root 建 chmod 700 /data/git/.ssh # ← 700 root:root # only chown if current owner is not already the gitea ${USER}. No recursive check to save time if ! [[ $(ls -ld /data/git | awk '{print $3}') = ${USER} ]]; then chown -R ${USER}:git /data/git; fi那个递归 chown 有守卫:只有当
/data/git的属主不是git时才执行。如果/data/git已经是git而里面某个文件(如刚被 root 建出来的.ssh)是root:root, 守卫为假 → 递归 chown 被跳过 →.ssh永久留在root:root 700。Gitea 以git运行, 写不进去:[F] gitea.dev/services/asymkey.RewriteAllPublicKeys(ctx) failed: open /data/git/.ssh/authorized_keys.tmp: permission denied后果是容器
Restarting死循环、/api/healthz无响应、Apache/QA返回 503。 同样的守卫也作用于/data/gitea, 所以conf、log也可能变成root:root。体检与修复(迁移后 / 恢复后建议各跑一次):
sudo docker compose exec -T gitea ls -ld /data/git /data/git/.ssh /data/gitea/conf /data/gitea/log # 期望属主全是 git(git)。若出现 root: sudo chown -R 982:982 /srv/gitea/git /srv/gitea/gitea/conf /srv/gitea/gitea/log sudo docker compose restart gitea
⚠️ 3. 定制覆盖层的文件权限 —— 又一次让 Gitea 以
[F]崩溃。customization/custom/*是只读挂载进容器的, 容器里 Gitea 以git(982) 运行。 如果这些文件是600(只读挂载不影响权限检查!), 启动时就报:[F] processStartupTemplateError() Gitea can't run with template errors: open home.tmpl: permission denied容器
Restarting死循环。预览环境不会暴露这个问题 —— 预览容器用PREVIEW_UID(默认宿主 uid 1001), 恰好就是文件属主, 所以 600 也读得到。# 体检: 容器用户能否读到 docker compose exec -T -u git gitea head -c1 /data/gitea/templates/home.tmpl # 修复(会遍历 custom/ 补齐 g+r / o+r, 目录补 o+x) python3 ../customization/build.py python3 ../customization/build.py --check # 部署前也会校验, 不可读直接报错退出编辑器/工具写文件常带
600;git只记录可执行位, 所以新克隆下来一般是 644, 偏偏本地改过的文件会中招。
⚠️ 4. 站点名
APP_NAME只能用裸变量,GITEA__DEFAULT__APP_NAME无效。 镜像的/etc/s6/gitea/setup用envsubst渲染/etc/templates/app.ini, 而模板第一行是APP_NAME = $APP_NAME—— 来源是裸环境变量APP_NAME。为什么GITEA__*那条路走不通:modules/setting/config_env.go会把段名小写化(section = strings.ToLower(section)), 而 ini 库(gopkg.in/ini.v1)的默认段名常量是"DEFAULT"(大写, 且默认区分大小写), 所以GITEA__DEFAULT__X只会新建一个没用的[default]段, 顶层键纹丝不动。 症状: 页面标题变成Gitea: Git with a cup of tea。而且模板只在
app.ini不存在时渲染, 所以对已经生成过app.ini的部署, 光改 env 不够, 必须让容器重新生成一次:sudo rm -f /srv/gitea/gitea/conf/app.ini sudo docker compose up -d --force-recreate gitea
⚠️ 5. 用
curl验证本机服务时会被 HTTP 代理接管。 本机 shell 里设了http_proxy=127.0.0.1:7890, 而no_proxy不覆盖127.0.0.1时, 连curl http://127.0.0.1:2080/...都会走 mihomo, 而 mihomo 对回环代理请求返回502 Bad Gateway(响应头带Proxy-Connection: keep-alive, 是代理在答而不是 Gitea)。 表现为"经 Apache 200、直连 502"的假故障。所有脚本(
verify.sh/restore.sh)内部都已--noproxy '*'; 手工验证时也要加:curl -sS --noproxy '*' http://127.0.0.1:2080/api/healthz
⚠️ 6. compose 会把 shell 的
http_proxy注入容器 —— 会让 OIDC 登录整条 404。docker compose up会自动把运行它的那个 shell 里的HTTP_PROXY/HTTPS_PROXY/NO_PROXY(大小写都算)注入容器。本机登录 shell 里是http_proxy=http://localhost:7890,而localhost/127.0.0.1在容器里指向容器自己, 于是 Gitea 启动时拉 OIDC discovery 失败:initOAuth2Sources() [E] Unable to register source: 高程统一身份认证 due to Error: Failed to initialize OpenID Connect Provider ... proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused认证源注册不上 → 登录页的按钮还在(它来自数据库), 但点下去
/QA/user/oauth2/...返回 404, 统一身份认证完全无法登录。 这个坑很隐蔽: 容器是健康的、健康检查200、登录页200, 只有真正点登录才炸。
compose.yaml现在显式给出这几个变量、且默认空值(= 容器内不用代理), 显式赋值可以挡住自动注入。默认不用代理的依据(2026-09-13 实测):
- 容器直连外网是通的:
dl.gitea.com、api.github.com、codeload.github.com在容器里直接 curl 分别是200/200/301(github.com主站直连会超时, 但平台不依赖它);- 与功能相关的出站只有 OIDC, 目标是
10.80.42.185, 容器内直连即200;- 宿主
7890那个代理是 ssh 转发的开发用代理,ss -ltn显示只监听127.0.0.1:7890/[::1]:7890—— 在容器里127.0.0.1是容器自己,10.80.42.185:7890也不可达(实测curl -x直接Could not connect), 所以这个代理配进容器只会让出站先绕一圈再失败。将来真要给容器配代理, 必须是容器可达的地址(把隧道绑到 LAN 口, 或让容器用 host 网络), 再在
.env里给GITEA_HTTP_PROXY(见.env.example)。 每次up -d后建议验一次 OIDC 入口是否还通:curl -sS --noproxy '*' -o /dev/null -w '%{http_code} %{redirect_url}\n' \ 'http://127.0.0.1:2080/user/oauth2/%E9%AB%98%E7%A8%8B%E7%BB%9F%E4%B8%80%E8%BA%AB%E4%BB%BD%E8%AE%A4%E8%AF%81' # 期望: 307 + Location: https://cpp.tongji.sh/oidc/auth?... (404 = 认证源没注册上)⚠️ 7. 全新克隆 + compose: docker 会以 root 创建不存在的挂载源目录。
compose.yaml把customization/custom/{options,public,templates}逐个挂进容器。 其中options/里只有生成出来的locale_zh-CN.json, 而它是 gitignore 的 —— 于是 全新克隆里这个目录不存在, docker 会以 root 创建它, 之后普通用户跑customization/build.py就写不进去:PermissionError: [Errno 13] Permission denied: .../custom/options/locale后果不是报错那么明显: 语言文件生成失败 → 中文界面退回上游文案(「工单」又回来了), 而首页/登录页看起来一切正常。2026-09-13 第一次把生产切到部署克隆(CI 用的那份)时踩到。
现在有两道防线: ①仓库里
customization/custom/options/.gitkeep让目录随 checkout 就存在 且属于当前用户; ②deploy/scripts/auto-deploy.sh在部署前检查三个目录存在且可写, 不满足就明确报错。若已经中招:sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可⚠️ 8. act_runner 的 job 容器不要自己挂
docker.sock。 act_runner 会把 docker daemon socket 自动挂进 job 容器(container.docker_host的默认 行为); 再在deploy/runner/config.yaml的container.options里挂一次, 第一次真实部署 就会以这个错误告终:failed to create container: 'Duplicate mount point: /var/run/docker.sock'2026-09-13 用
act_runner exec预演 job 时提前发现。container.options里只保留 部署克隆(同路径)、宿主 docker CLI、compose 插件这三项。⚠️ 9. 宿主
/usr/bin/python3是 3.6, 别让它排到 PATH 前面。customization/build.py用了from __future__ import annotations, 需要 ≥3.7。 宿主上正确的解释器是~/.local/bin/python3(3.14), 但/usr/bin/python3是 Rocky 8 的 3.6 —— 只要 PATH 被改成/usr/bin优先, 就会看到SyntaxError: future feature annotations is not defined, 而且语言文件静默地不再更新。auto-deploy.sh现在自己挑一个 ≥3.7 的解释器(并用它跑 build.py), 不依赖 PATH 顺序。
3. 本机关键事实
| 项目 | 实测值 |
|---|---|
| 系统 / 架构 | Rocky Linux 8.10 / aarch64 |
| 对外地址 | https://cpp.tongji.sh/QA(Apache ProxyPass /QA http://localhost:2080) |
| 数据目录 | /srv/gitea(Gitea)、/srv/pgdata/18/docker(PG) |
| git 用户 | uid/gid = 982:982(容器内 USER_UID/USER_GID 必须对齐) |
| 库属性 | UTF8 / zh_CN.UTF-8 |
| 防火墙 | firewalld 已装但未运行; SELinux Disabled |
| Docker | CE 29.8.0(rhel/8 源), compose 插件 5.5.1 |
⚠️ Docker 源必须用
linux/rhel/8。linux/centos/8源在 CentOS 8 EOL 后已冻结在docker-ce 26.1.3(2024-04), 照抄 CentOS 教程会装到三年前的老引擎。
4. 部署(全新主机)
4.1 前置条件
- Rocky Linux 8(aarch64), 有
sudo/ root; - 宿主机已有 Apache 反代到
127.0.0.1:2080(本方案不改 Apache); - 规划好数据目录(默认
/srv/gitea、/srv/pgdata), 确保有空间。
4.2 安装 Docker CE
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install -y --allowerasing \
docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker --version && docker compose version
--allowerasing 是必需的, 不是可选项。 首次按常规方式安装会失败:
package containerd.io-2.3.5-1.el8.aarch64 conflicts with runc provided by runc-4:1.2.9-6.module+el8.10.0+40310...
package containerd.io-2.3.5-1.el8.aarch64 obsoletes runc provided by runc-4:1.2.9-6.module+el8.10.0+40310...
package podman-4:4.9.4-37... requires runc >= 1.0.0-57, but none of the providers can be installed
根因(已逐个版本核对 Docker 源的 primary.xml): Docker 源内全部 30 个版本的
containerd.io 都 Obsoletes + Conflicts: runc, 而 Rocky 8 的 runc 被
containers-common、podman、buildah 依赖。所以这不是版本问题 —— 换老版本 Docker
一样冲突。Docker CE 与系统 podman 只能二选一。
--allowerasing 会由 containerd.io 取代 runc(它自带 runc 二进制), 连带移除 6 个包:
runc podman podman-catatonit buildah containers-common cockpit-podman。
执行前先确认这些包没在承载东西:
podman ps -a为空、无镜像、无 Quadlet 单元,cockpit.socketinactive + disabled。装完 docker-ce 后 podman 与 docker 不能再共存; 想要回 podman 必须先卸载 docker-ce。不接受移除的, 见附录 A。
4.3 配置外网代理(dockerd 不继承 shell 变量)
本机访问 docker.io 必须走代理(7890), 但 dockerd 由 systemd 启动, 不会继承你 shell 里的
http_proxy/https_proxy —— 所以 curl 能通、docker build 却报 dial tcp ...: i/o timeout。
雪上加霜的是本机对 registry-1.docker.io 的 DNS 被污染(实测解析到
2a03:2800:f10f:83:face:b00c:..., Facebook 地址段), 直连必然超时; 走 HTTP 代理时由代理
负责解析域名, 反而正常:
| 目标 | 直连 | 经代理 127.0.0.1:7890 |
|---|---|---|
registry-1.docker.io |
000(15s 超时) |
401(0.9s, 正常响应) |
docker.gitea.com |
200 |
200 |
代理要配到三个互相独立的地方, 缺一个就有一类操作不生效:
| 层 | 文件 | 作用 |
|---|---|---|
dockerd |
/etc/systemd/system/docker.service.d/http-proxy.conf |
镜像拉取 |
containerd |
/etc/systemd/system/containerd.service.d/http-proxy.conf |
兜底 |
| CLI / BuildKit | ~/.docker/config.json 的 proxies 段 |
自动给 RUN 步骤注入代理参数 |
# 1) dockerd
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf >/dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1,.local,.internal"
EOF
# 2) containerd
sudo mkdir -p /etc/systemd/system/containerd.service.d
sudo tee /etc/systemd/system/containerd.service.d/http-proxy.conf >/dev/null <<'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart containerd docker
# 3) CLI / BuildKit(当前用户; 用 sudo 跑 docker 时也要给 root 配一份)
mkdir -p ~/.docker
cat > ~/.docker/config.json <<'EOF'
{
"proxies": {
"default": {
"httpProxy": "http://127.0.0.1:7890",
"httpsProxy": "http://127.0.0.1:7890",
"noProxy": "localhost,127.0.0.1,::1"
}
}
}
EOF
sudo cp ~/.docker/config.json /root/.docker/config.json 2>/dev/null || true
# 端到端验证
docker pull hello-world
已知坑: BuildKit 解析
FROM时不走这个代理。docker pull postgres:18.6走 dockerd 自己的 registry 客户端, 会遵守上面的 drop-in; 但docker compose build里[internal] load metadata那一步是 BuildKit 在解析FROM docker.io/library/postgres:18.6, 它会绕过代理直连, 对auth.docker.io做本地 DNS 查询(报lookup auth.docker.io on 202.120.190.208:53: i/o timeout)。 本机没有独立buildkitd、没有自定义 builder、没有daemon.json, BuildKit 内嵌在 dockerd 里 —— 也就是说代理变量在场却未被采用, 属 BuildKit 解析器的行为, 不是配置写错。规避办法: 先用
docker pull把基础镜像拉到本地(见 4.5), 之后 BuildKit 直接命中 本地镜像, 不再访问 registry。
还有第四件事: 容器内部的代理(例如让 Gitea 去拉外部头像 / 发外部 webhook)。 那是 compose
environment:的事。当前GITEA_OFFLINE_MODE=true, 暂不需要。
4.4 配置 .env
cd /home/ymy/tjhlp-gitea/deploy
cp .env.example .env
$EDITOR .env
必须有值的键(其余有默认值):
| 键 | 说明 |
|---|---|
GITEA_ROOT_URL / GITEA_DOMAIN |
必须与 Apache 反代一致, 否则克隆地址与链接会错 |
GITEA_HTTP_PORT |
必须等于 Apache ProxyPass 的目标端口(本机 2080) |
GITEA_APP_NAME |
站点名, 走裸变量(陷阱 3) |
GITEA_DATA_DIR / POSTGRES_DATA_DIR |
数据落盘位置 |
GITEA_UID / GITEA_GID |
必须等于数据目录属主(本机 982:982) |
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD |
数据库 |
GITEA_INTERNAL_TOKEN / GITEA_LFS_JWT_SECRET / GITEA_OAUTH2_JWT_SECRET |
密钥, 生成见下 |
GITEA_SECRET_KEY |
见 §11; 留空 = 用 Gitea 内置默认值 |
# 生成密钥
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret INTERNAL_TOKEN
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret LFS_JWT_SECRET
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret JWT_SECRET # -> OAUTH2_JWT_SECRET
docker run --rm docker.gitea.com/gitea:1.27.3 gitea generate secret SECRET_KEY
校验配置(取代了早先的 preflight.sh; 只读, 不需要 daemon):
docker compose config --quiet && echo "compose 插值 OK"
docker compose config | grep -E 'APP_NAME|ALLOWED_HOST|image:' # 抽查关键项
4.5 启动
cd /home/ymy/tjhlp-gitea/deploy
# ★ 先预拉基础镜像, 绕开 BuildKit 的 FROM 解析(见 4.3)
docker pull docker.io/library/postgres:18.6
docker pull docker.gitea.com/gitea:1.27.3
docker compose up -d --build
docker compose ps
首次启动 db 会 initdb(UTF8 + zh_CN.UTF-8), gitea 会自动建表。
4.6 验证
sudo ./scripts/verify.sh
检查: 两个容器 healthy、/api/healthz 200、/api/v1/version 版本正确、经 Apache /QA 200。
站点名与登录源可以单独确认:
curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -o '<title>[^<]*</title>'
# 期望: <title>Sign In - 你的站点名</title>
locale 是否真的生效:
docker compose exec -T db psql -U gitea -d giteadb -tAc \
"select datname, pg_encoding_to_char(encoding), datcollate from pg_database where datname='giteadb'"
# 期望: giteadb | UTF8 | zh_CN.UTF-8
4.7 收尾
若是从宿主二进制部署迁移过来的, 必须停用宿主 unit。 否则重启后宿主 gitea 与容器会抢
127.0.0.1:2080 —— 两边都会开机自启(docker.service enabled, 容器
restart: unless-stopped), 谁先 bind 谁赢。若宿主赢了, 平台会静默地退回旧库运行:
容器起不来, 但 Apache /QA 依然返回 200, 从外部完全看不出来。
sudo systemctl disable gitea # 容器侧开机会自己回来, 不需要宿主 unit
要不要把用户加进 docker 组? 加了确实方便 —— docker 命令不用 sudo,
verify.sh / backup.sh / restore.sh 都能直接跑。但这是一次实打实的权限降级:
docker组等价于免密 root。 组内用户可以docker run -v /:/host -it alpine chroot /host直接拿到宿主 root shell。 Docker 官方文档同样说明 "The docker group grants root-level privileges to the user" (https://docs.docker.com/engine/install/linux-postinstall/)。wheel与docker组的区别就在密码。 已加入wheel的话sudo需要输密码;docker组不需要。一旦有人拿到一个ymy的 shell(SSH 会话劫持、被投毒的脚本或依赖、 code-server 会话),wheel还挡着一道密码,docker组则直接就是 root。- 这台机器是共享的。 Apache/PHP 对整个平台提供 Web 服务, 还跑着 MySQL、Redis、 code-server。root 沦陷的爆炸半径是整台机器, 不只是 Gitea。
建议: 不加, 继续用 sudo。 日常 docker 命令用得很少 —— restart: unless-stopped
让容器开机自动拉起, 平时只有偶尔看日志/升级/备份, sudo 的开销基本可忽略。
若确实想要免密, 比进 docker 组更安全的做法是给一个只放行固定动作的 wrapper +
sudoers 规则(不能直接放行裸 docker, 那等于没限制):
# /usr/local/sbin/gitea-ctl —— 只暴露固定动作
#!/usr/bin/env bash
cd /home/ymy/tjhlp-gitea/deploy || exit 1
case "${1:-}" in
up) exec docker compose up -d ;;
down) exec docker compose down ;;
ps) exec docker compose ps ;;
logs) shift; exec docker compose logs --tail=200 "$@" ;;
verify) exec ./scripts/verify.sh ;;
backup) exec ./scripts/backup.sh --quiesce ;;
*) echo "用法: gitea-ctl {up|down|ps|logs|verify|backup}" >&2; exit 1 ;;
esac
# /etc/sudoers.d/gitea-ctl (先用 visudo -f 校验再生效)
ymy ALL=(root) NOPASSWD: /usr/local/sbin/gitea-ctl
5. 备份
cd /home/ymy/tjhlp-gitea/deploy
sudo ./scripts/backup.sh # 在线备份(不中断服务)
sudo ./scripts/backup.sh --quiesce # 先停 gitea 再备份, 一致快照(推荐)
必须用 root 跑: 打包 GITEA_DATA_DIR 时要读取 .ssh 等 700 目录, 并且要保留文件属主。
产物在 deploy/backups/<时间戳>/:
| 文件 | 内容 |
|---|---|
postgres-<db>.dump |
pg_dump -Fc 自定义格式, 用 pg_restore 恢复 |
gitea-data.tar.gz |
GITEA_DATA_DIR 全量打包(容器布局) |
MANIFEST.txt |
时间/主机/镜像/大小 |
SHA256SUMS |
校验和, restore.sh 恢复前会验证 |
--quiesce 与在线备份的区别: 在线备份时 Gitea 仍在写库/写仓库, 两份产物之间存在时间差,
极端情况下恢复出来的"库"与"仓库"不一致。做重要节点(升级前、迁移前)一律用 --quiesce。
定期备份(root 的 crontab, 每天 03:00 一致快照):
sudo crontab -e
# 0 3 * * * cd /home/ymy/tjhlp-gitea/deploy && ./scripts/backup.sh --quiesce >> /var/log/gitea-backup.log 2>&1
保留策略: 备份目录不会被自动清理, 需要自己 prune(数据只有几 MB, 但 pg_dump 有 40 MB
上下)。建议保留最近 7 份 + 每月 1 份, 并异地留一份 —— 同一块盘上的备份挡不住盘坏。
可以改 BACKUP_DIR 指向外部挂载点。
⚠️
backup.sh产出的是容器布局的数据包。历史遗留的deploy/backups/pre-migration-*/gitea-source-data.tar.gz是二进制部署时期的宿主布局 (gitea/data/gitea-repositories/...), 不能用restore.sh恢复数据目录(脚本会拒收)。 那些备份只有postgres-giteadb.dump还能用(--db-only)。
6. 恢复
cd /home/ymy/tjhlp-gitea/deploy
# 1) 看有哪些备份, 以及校验状态(不需要 root)
./scripts/restore.sh --list
# 2) dry-run: 校验校验和 + 打印恢复计划, 不动任何东西
./scripts/restore.sh 20260912-030000
# 3) 真正执行
sudo ./scripts/restore.sh 20260912-030000 --apply
选项:
| 选项 | 作用 |
|---|---|
--db-only |
只恢复数据库(数据目录不动) |
--data-only |
只恢复数据目录(库不动) |
--no-safety-backup |
跳过"恢复前先备份当前状态"(不建议) |
--apply 的执行顺序:
- 校验
SHA256SUMS—— 任一文件不匹配立即中止; - 跑一次
backup.sh --quiesce, 把当前状态存下来(恢复错了还能退回去); docker compose up -d db并等healthy;docker compose stop gitea;- 数据目录: 先把现有目录改名成
${GITEA_DATA_DIR}.pre-restore-<时间戳>(不删除), 再解包备份, 然后chown -R 982:982; - 数据库:
pg_restore --clean --if-exists --no-owner, 并打印恢复后的表数量; docker compose up -d gitea, 等healthy, 跑verify.sh;- 打印数据目录的回退命令。
脚本失败或恢复错了, 按它打印的命令回退:
sudo docker compose stop gitea
sudo rm -rf /srv/gitea && sudo mv /srv/gitea.pre-restore-<时间戳> /srv/gitea
sudo docker compose start gitea
手工等价的恢复命令(脚本不可用时):
sudo docker compose stop gitea
docker compose exec -T db pg_restore -U gitea -d giteadb --clean --if-exists --no-owner \
< backups/<时间戳>/postgres-giteadb.dump
sudo mv /srv/gitea /srv/gitea.bak && sudo tar -C /srv -xzf backups/<时间戳>/gitea-data.tar.gz
sudo chown -R 982:982 /srv/gitea
sudo docker compose up -d
演练建议: 至少每学期做一次 —— 在测试机上把最新备份
--apply一遍, 确认站点能起来、 仓库能 clone、Issue 都在。备份坏了通常是恢复的那一刻才发现。
恢复后若 Gitea 报 [F] ... permission denied, 见陷阱 2 的体检命令。
7. 升级
第一步永远是备份。 Gitea 的数据库迁移不可逆 —— 升级后想退回旧镜像, 旧版本很可能 因为 schema 版本比它新而拒绝启动, 唯一退路就是备份。
7.1 升级 Gitea
cd /home/ymy/tjhlp-gitea/deploy
# 1) 备份(必做)
sudo ./scripts/backup.sh --quiesce
# 2) 读 release notes, 确认没有 breaking change
# https://github.com/go-gitea/gitea/releases
# 3) 改版本
sed -i 's/^GITEA_VERSION=.*/GITEA_VERSION=1.28.0/' .env # 或 $EDITOR .env
# 4) 同步定制基线: 拉上游快照 → 合并模板改动 → 重新生成语言文件
# (详见 ../customization/README.md; build.py 会因「覆盖的键不存在」而报错,
# 把上游改键名/删键的风险挡在部署之前)
../customization/fetch-upstream.sh 1.28.0
# 手动 diff upstream/ 并更新 customization/custom/templates/*.tmpl
python3 ../customization/build.py --check
# 5) 拉取并重建
docker compose pull gitea
docker compose up -d gitea
# 6) 看迁移日志 + 验证
docker compose logs --since 5m gitea | grep -iE 'migrat|error|\[F\]'
sudo ./scripts/verify.sh
curl -s https://cpp.tongji.sh/QA/ | grep -c 课程答疑平台 # 抽查定制仍在生效
回滚: 把 GITEA_VERSION 改回旧值 → docker compose up -d gitea。
若旧版本因 schema 更新而拒绝启动, 用 §6 恢复升级前的备份。
7.2 升级 PostgreSQL
小版本(18.6 → 18.7): 可以直接改, PG 保证 minor 版本 on-disk 兼容。
sudo ./scripts/backup.sh --quiesce
sed -i 's/^POSTGRES_VERSION=.*/POSTGRES_VERSION=18.7/' .env
docker compose up -d --build db # POSTGRES_VERSION 是 build arg, 要重建镜像
sudo ./scripts/verify.sh
大版本(18 → 19): 不能只改版本号。 数据目录布局与 on-disk 格式都不兼容, 必须把数据
导出再导入。因为 pg_dump 的产物跨大版本可读, 这条路最稳:
cd /home/ymy/tjhlp-gitea/deploy
sudo ./scripts/backup.sh --quiesce # 得到 postgres-giteadb.dump
docker compose down
sudo mv /srv/pgdata /srv/pgdata.pg18 # 保留旧集群, 不删
sed -i 's/^POSTGRES_VERSION=.*/POSTGRES_VERSION=19.0/' .env
docker compose up -d --build db # 用新版本 initdb(仍带 zh_CN.UTF-8)
# 灌回数据
docker compose exec -T db pg_restore -U gitea -d giteadb --clean --if-exists --no-owner \
< backups/<时间戳>/postgres-giteadb.dump
docker compose up -d gitea
sudo ./scripts/verify.sh
⚠️ 大版本升级会换掉
PGDATA的路径层级(/var/lib/postgresql/<ver>/docker), 所以POSTGRES_DATA_DIR本身不用改, 但旧目录一定要先改名保留, 确认新集群没问题再删。 另外pg_restore用的pg_restore二进制应来自新版本容器(本方案是在容器内执行, 天然满足)。
7.3 升级检查单
- 已
backup.sh --quiesce, 且restore.sh --list显示校验ok - 读过 release notes, 确认没有 breaking change(配置文件段位变更、弃用项)
- 避开发答疑高峰, 预留 30 分钟
- 升级后
verify.sh全绿 - 升级后日志无
[F]/[E] - 登录一次, 确认 OIDC 登录源与仓库 clone 正常
- 确认无误后再清理旧备份 / 旧数据目录
8. 日常运维
cd /home/ymy/tjhlp-gitea/deploy
docker compose ps # 状态(含 health)
docker compose logs -f --tail=100 gitea
docker compose restart gitea
sudo ./scripts/verify.sh # 完整体检
docker compose exec -T db psql -U gitea -d giteadb # 进库
改了 compose.yaml 或 .env 之后:
docker compose up -d # 增量生效(必要时 --force-recreate)
改了只由模板渲染的键(如 GITEA_APP_NAME)则要重建 app.ini, 见陷阱 3。
9. 回滚
回滚到宿主二进制部署(源数据与源库都还在原地, 迁移只复制不移动):
cd /home/ymy/tjhlp-gitea/deploy
docker compose down
sudo systemctl enable --now gitea # 之前 disable 过, 这里要 enable 回来
源数据 /var/lib/gitea 与源库 giteadb 未被修改, 立即恢复原状。
回滚一次升级: 见 §7 各小节。
10. 外部依赖: OAuth2/OIDC 登录源(高程统一身份认证)
库里有一条 login_source 记录(id=1), 指向
https://cpp.tongji.sh/oidc/.well-known/openid-configuration。这个服务的可用性不影响
Gitea 本身, 只影响该登录源能否注册。两类日志要分清:
| 日志 | 级别 | 含义 |
|---|---|---|
Failed to create OpenID Connect Provider ... Non-success code for Discovery URL: 503 |
[W]/[E] |
不致命。Gitea 跳过该源, 其余功能正常; 页面不显示该登录按钮 |
asymkey.RewriteAllPublicKeys ... permission denied |
[F] |
致命。进程退出, 容器重启循环(见陷阱 2) |
Gitea 只在启动时注册 OAuth2 源(initOAuth2Sources()), 所以:
IdP 恢复后, 必须重启 gitea 容器, 登录源才会被重新注册。
sudo docker compose restart gitea
IdP 侧改动后的验证步骤(从外到内, 任一步失败都会表现为同一个 503):
cd /home/ymy/tjhlp-gitea/deploy
# 1. 宿主机上能不能拿到 discovery 文档(走 Apache -> /oidc)
curl -sS --noproxy '*' -o /dev/null -w 'host -> %{http_code}\n' \
https://cpp.tongji.sh/oidc/.well-known/openid-configuration
# 2. 容器内能不能拿到(网络路径不同, 这一条才是 Gitea 真正走的)
sudo docker compose exec -T gitea curl -s -o /dev/null -w 'cont -> %{http_code}\n' \
https://cpp.tongji.sh/oidc/.well-known/openid-configuration
# 3. 重启后确认不再有注册失败
sudo docker compose restart gitea
sudo docker compose logs --since 2m gitea | grep -i 'register source' || echo "OK: 无注册失败"
# 4. 登录页上该登录源是否出现(应为 1 或更大)
curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -c '高程统一身份认证'
# 5. 库里的记录本身还在(与 IdP 无关, 只是确认没丢这条配置)
sudo docker compose exec -T db psql -U gitea -d giteadb -tAc \
"select id,name,is_active from login_source"
第 1 步通、第 2 步不通, 通常是容器到宿主机 IP 的可达性问题(而不是 IdP 的问题);
两步都 503 才是 IdP 侧还没起来。第 4 步为 0 说明源仍未注册成功。
11. SECRET_KEY 与安全
Gitea 源码 modules/setting/security.go:
SecretKey = loadSecret(sec, "SECRET_KEY_URI", "SECRET_KEY")
if SecretKey == "" {
// FIXME: ... Until it supports rotating an existing secret key,
// we shouldn't move users off of the widely used default value
SecretKey = "!#@FDEWREWR&*("
}
也就是说: 本实例一直在用这个公开的内置常量。官方文档对 SECRET_KEY 的说明是
"if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore"。
本实例的受影响面很小(已核对): two_factor = 0, webauthn_credential = 0,
唯一的加密相关对象是 1 个 OAuth2 登录源「高程统一身份认证」。
- 默认:
.env里GITEA_SECRET_KEY留空 → 沿用同一默认值, 行为完全不变, SSO 不受影响。 - 加固(可选, 需单独安排窗口): 生成随机
SECRET_KEY写入.env→docker compose up -d gitea→ 到管理后台重新填写 OIDC 登录源的 Client Secret (这会让它用新密钥重新加密) → 验证 SSO 登录。跳过重配会导致 OIDC 登录失败。
其它安全要点:
- PostgreSQL 不能发布端口到宿主机; Gitea 只发布回环(见 §1)。
.env含密钥, 已被.gitignore排除, 不要提交。.env值里含$要写成$$(compose 会做变量插值); 含#或空格要用引号。
12. 故障排查速查
| 症状 | 先看 | 处置 |
|---|---|---|
容器 Restarting 死循环, /api/healthz 不通 |
docker compose logs gitea | grep '\[F\]' |
permission denied → 陷阱 2 |
页面标题是 Gitea: Git with a cup of tea |
§2 陷阱 3 | 删 app.ini 重建 |
db 容器起不来, 日志提 unused mount/volume |
§2 陷阱 1 | 挂载点应为 /var/lib/postgresql |
curl 127.0.0.1:2080 返回 502 |
§2 陷阱 4 | 加 --noproxy '*' |
登录页没有 高程统一身份认证 |
§10 | 确认 IdP 可达后 restart gitea |
| 重启后平台"正常但数据是旧的" | — | 宿主 gitea.service 抢了 2080, 见 §4.7 |
docker build 报 lookup auth.docker.io ... i/o timeout |
§4.3 | 先 docker pull 基础镜像 |
docker pull 报 i/o timeout |
§4.3 | 代理 drop-in 没生效, systemctl show docker -p Environment |
| 容器 healthy 但站点 503 | docker compose logs gitea |
多为 .env 里 DB 密码与既有数据不一致 |
13. 附录 A: RPM 冲突的三条路线
因为 containerd.io 与发行版 runc 互斥(§4.2), 本机只有三种选择:
| 路线 | 系统改动 | 代价 |
|---|---|---|
A. Docker + --allowerasing(已采用) |
移除 runc/podman/podman-catatonit/buildah/containers-common/cockpit-podman |
与 podman 二选一; 得到 dnf 托管的 Docker CE 29.8.0 |
| B. 保留 podman, 用 Docker 静态二进制 | 不动任何 RPM, 只往 /usr/local/bin 放文件 |
不受 dnf 管理: 升级手工做, systemd unit 自己维护 |
| C. 放弃 Docker, 纯 Podman | 零改动 | 需额外 compose provider; depends_on: service_healthy 语义弱, 可能要改写 Quadlet |
B. Docker 静态二进制(保留 podman)
curl -fsSLo /tmp/docker.tgz https://download.docker.com/linux/static/stable/aarch64/docker-29.8.0.tgz
tar -C /usr/local --strip-components=1 -xzf /tmp/docker.tgz # dockerd/containerd/runc/docker...
mkdir -p /usr/local/lib/docker/cli-plugins
curl -fsSLo /usr/local/lib/docker/cli-plugins/docker-compose \
https://github.com/docker/compose/releases/latest/download/docker-compose-linux-aarch64
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
静态包自带 runc/containerd, 不碰 RPM 数据库, 因此与 podman 无冲突;
但需要自备 systemd unit(Type=notify, ExecStart=/usr/local/bin/dockerd)。
C. 纯 Podman
sudo dnf install -y podman-compose # 或用 Go 版 docker-compose 二进制作 provider
podman compose up -d
注意:
- rootless 容器要开机自启/登出后存活, 需要
sudo loginctl enable-linger <user>; - 本机 Podman 网络后端是较老的 CNI; 若将来启用 firewalld,
firewall-cmd --reload可能清掉 Podman 规则, 需要podman network reload; - 换哪条路线, 容器发布的回环端口都不变, Apache 依旧不用改。
14. 附录 B: 二进制 → 容器迁移(已完成, 仅存档)
本机原有部署是 Gitea 1.27.3 二进制 + systemd + 宿主 PostgreSQL 18.6
(ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini, 监听 0.0.0.0:2080)。
迁移已于 2026-09-11 完成, 当时用的一次性脚本(migrate-from-binary.sh /
install-docker.sh / configure-docker-proxy.sh / preflight.sh)已按"一次性"清理掉,
过程留档如下。
做法: systemctl stop gitea → rsync 复制数据(复制, 不移动)→
docker compose up -d --build db 建新集群 → pg_restore 灌库并核对表数量 →
up -d gitea → 验证。源数据与源库全程未改, 因此回滚只需 docker compose down && systemctl start gitea(§9)。
当时的迁移前备份: deploy/backups/pre-migration-*/(7 份, 每份含
postgres-giteadb.dump + gitea-source-data.tar.gz)。注意数据包是宿主布局,
只能 restore.sh --db-only 用, 见 §5 的警告。
与宿主 app.ini 的有意差异
除"路径改为容器语义"外, 以下是有意为之的行为变化:
| 配置 | 迁移前 | 现在 | 原因 |
|---|---|---|---|
log.MODE |
file |
console |
日志进 stdout, 用 docker compose logs 收集 |
server.DISABLE_SSH |
false |
true |
实测 /home/git/.ssh 不存在, SSH 从未使用; 避免暴露无法工作的克隆地址 |
server.DOMAIN |
localhost |
实际主机/IP | localhost 会生成错误的克隆地址; ROOT_URL 已显式指定, 此项属修正 |
security.ALLOWED_HOST_LIST |
[security](正确) |
保持 [security] |
1.27 的规范位置就是 [security]; [webhook] 是 v28.0.0 将移除的 deprecated fallback |
server.HTTP_ADDR |
0.0.0.0:2080 |
容器内 0.0.0.0, 宿主只发布 127.0.0.1:2080 |
保持 Apache 反代路径不变, 同时消除直连暴露面 |
oauth2.ENABLED |
未设置(默认 true) |
显式 true |
防止上游改默认值导致漂移 |
其余配置(注册策略、OIDC 自动注册、admin 限制、pull-request/signing 默认值、
PASSWORD_HASH_ALGO=pbkdf2、OFFLINE_MODE、webhook TLS 等)均按原值 1:1 保留。
迁移中发现并处理的既有问题:
| # | 问题 | 证据 | 处理 |
|---|---|---|---|
| 1 | 未设置 SECRET_KEY |
/etc/gitea/app.ini 无该键 |
保持默认, 见 §11 |
| 2 | 监听 0.0.0.0:2080 |
ss -ltn 显示 *:2080; firewalld 未运行 |
容器只发布 127.0.0.1:2080 |
| 3 | /oidc 反代指向死端口 |
httpd.conf 里 ProxyPass /oidc http://localhost:3000/oidc, 而 3000 无监听 |
IdP 侧问题, 见 §10 |
| 4 | 数据目录里留着 amd64 包 | /var/lib/gitea/gitea-1.26.1-linux-amd64.xz(本机是 arm64) |
新数据目录不含它 |
15. 文件清单
deploy/
├── README.md 本文档(部署 / 备份 / 恢复 / 升级)
├── compose.yaml 服务定义(版本锁定 / 回环发布 / 环境变量注入配置)
├── .env.example 配置模板(复制为 .env)
├── db/Dockerfile postgres + zh_CN.UTF-8 locale(版本由 build arg 传入)
├── backups/ 备份产物(.gitignore 排除)
└── scripts/
├── backup.sh 备份: pg_dump + 数据 tar + SHA256SUMS
├── restore.sh 恢复: 默认 dry-run, 校验校验和后按备份还原
└── verify.sh 体检: 容器健康 + 回环 API + 经 Apache 反代
常用命令:
cd /home/ymy/tjhlp-gitea/deploy
docker compose config --quiet # 校验 compose 与 .env 插值
docker compose up -d --build # 启动 / 应用配置变更
docker compose ps && docker compose logs -f --tail=100 gitea
sudo ./scripts/verify.sh # 体检
sudo ./scripts/backup.sh --quiesce # 备份
./scripts/restore.sh --list # 看备份
sudo ./scripts/restore.sh <时间戳> --apply # 恢复
16. 验证状态(诚实声明)
已在本机实测通过(2026-09-11, Rocky 8.10 aarch64)
- Docker CE 29.8.0 安装(路线 A,
--allowerasing, podman/runc 已移除); docker.service/containerd.service的代理 drop-in 生效;db镜像构建成功(local/gitea-postgres:18.6-zh_CN);db容器healthy,initdb带--locale=zh_CN.UTF-8完成;pg_restore端到端跑通: 源 116 张表 → 目标 116 张表;- Gitea 容器
healthy,/api/healthz200,/api/v1/version= 1.27.3; - 经 Apache
/QA反代 200(与迁移前路径一致); - 站点名正确渲染:
<title>Sign In - 同济高程-答疑平台</title>; - OAuth2/OIDC 登录源
高程统一身份认证注册成功(discovery 200, 登录页出现); - 失败自动回滚(迁移脚本的 EXIT trap)三次实测生效。
本机踩到并已修复的坑
见 §2 的四个陷阱(postgres:18 挂载点、s6 chown 守卫、APP_NAME、代理回环 502),
以及验证脚本自身的三个缺陷: 回环探测被 HTTP 代理接管、启动竞态被误报为 FAIL、
状态码拼接成 502000。
仍未实测
restore.sh --apply的完整演练(只验证了--list与 dry-run 路径)—— 建议尽快照 §6 在测试机上真跑一遍;backup.sh的 cron 定时执行;environment-to-ini对含点号 section(如GITEA__cron.update_checker__ENABLED) 的处理 ——conf/app.ini已生成且实例工作正常, 但未逐项比对;- PostgreSQL 大版本升级流程(§7.2)—— 步骤按官方文档与 PG18 布局推导, 未实跑;
- 重启后"容器自动恢复 + 宿主 unit 已 disable"的组合(建议找时间
sudo reboot验一次)。