Files
tjhlp-gitea/deploy/README.md
T
admin 73ce8162aa
deploy / deploy (push) Skipped
feat(ci): 落地 main 自动部署的可复用件(runner 配置/部署脚本/定制断言/工作流)
按 deploy/ci-cd.md 方案把除推送触发之外的东西都准备好:

- customization/check.sh <base-url>: 把 preview.sh check 里的"定制生效"断言抽成
  任意实例可跑的脚本(首页/页脚/meta/官网链接/登录页两张卡/无通行密钥方框/
  无「工单」/无 example.com), 另加生产才有的 OIDC 入口 307 断言(404 = 认证源没注册上)。
  实测对生产 17/17 通过。
- deploy/scripts/auto-deploy.sh: build.py -> compose up -d -> verify.sh + check.sh,
  失败自动回滚到 deploy/.state/last-deployed; flock 串行; 结束时把 clone 所有权还给
  ymy(job 容器里是 root); 内网验证强制不走代理。
- deploy/runner/{compose.yaml,config.yaml,.env.example}: act_runner v0.6.1 跑在容器里
  (不需要 root), network: host + 同路径挂载部署克隆 + 宿主 docker CLI/compose 插件,
  capacity 1 保证部署串行。
- .gitea/workflows/deploy.yml: push main + workflow_dispatch, [skip deploy] 跳过,
  concurrency 串行, 只做"同步到 github.sha + 调 auto-deploy.sh"。
- .gitignore: deploy/.state/、deploy/runner/{.env,data/}。

依据见 deploy/ci-cd.md(含全部实测证据与待确认项)。
2026-09-13 22:09:32 +08:00

44 KiB

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

三条铁律:

  1. 任何升级 / 迁移 / 改动前先备份 —— sudo ./scripts/backup.sh --quiesce。
  2. 没演练过的备份不算备份 —— 定期照 §6 在测试机上恢复一次。
  3. 配置只改 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.socket inactive + 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 的执行顺序:

  1. 校验 SHA256SUMS —— 任一文件不匹配立即中止;
  2. 跑一次 backup.sh --quiesce, 把当前状态存下来(恢复错了还能退回去);
  3. docker compose up -d db 并等 healthy;
  4. docker compose stop gitea;
  5. 数据目录: 先把现有目录改名成 ${GITEA_DATA_DIR}.pre-restore-<时间戳>(不删除), 再解包备份, 然后 chown -R 982:982;
  6. 数据库: pg_restore --clean --if-exists --no-owner, 并打印恢复后的表数量;
  7. docker compose up -d gitea, 等 healthy, 跑 verify.sh;
  8. 打印数据目录的回退命令。

脚本失败或恢复错了, 按它打印的命令回退:

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/healthz 200, /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 验一次)。