SHA256
forked from course-team/tjhlp-gitea
事故经过(2026-09-22): 「提问指南」换地址那个提交推送后 CI 挂了, auto-deploy 回滚。 check.sh 报「没找到官网提问指南链接 / 仍有旧地址」—— 但脚本确实把部署克隆同步到了新 提交、语言文件也重新生成了。原来 deploy() 比较的是 build.py 运行【前后】的指纹: 那只能 发现语言文件被重新生成, 纯模板改动前后完全一样 → 从不重启 → 容器继续用启动时加载的旧 模板 → 断言失败 → 整个部署被判失败并回滚。也就是说: 任何只改模板的提交都必然挂 CI。 修法: 把指纹记在 deploy/.state/custom-hash 里, 与【上次成功部署】的指纹比较, 不同就 restart gitea(restart 而不是 up -d: compose 配置没变时 up -d 不重建容器)。rollback 路径 改成 deploy force 无条件重启 —— 失败的那次可能已经用新模板重启过容器, 回滚必须再重启 回去, 顺便也修好下面这个副作用。 顺带修一个 bind mount 的坑: 挂载【源目录】被「删掉再建」后容器里挂的还是旧 inode(空 目录)。这次事故里 public/ 下的文件被删光、git 顺手删掉空目录, 于是线上 /QA/assets/tjhlp/ask-guide.html 变成 404。已在预览上复现([B] 404 → restart 后 [C] 200), restart 会重新解析挂载, 所以上面的修法同时把它修好。 验证(不碰生产的沙箱, 假 docker + 桩 verify/check): 1 全新状态首次部署 → up -d + restart ✓ 2 什么都没改再部署 → 不重启 ✓ 3 只改一个模板文件 → 重启 ✓(这次的回归点) 4 之后再来一次 → 不重启 ✓ 5 check 失败 → 回滚 → checkout PREV + 强制 restart ✓, 状态文件不被污染 ✓ 另外 check.sh / preview.sh 的失败信息里加了「模板改动要重启才生效」的提示, 并把 ci-cd.md §5.2(脚本清单+为什么必须 restart)与 README §12 速查表同步更新。
970 lines
45 KiB
Markdown
970 lines
45 KiB
Markdown
# 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`](../customization/README.md) | `python3 customization/build.py` → `docker compose restart gitea` |
|
|
| main 推送后自动部署(方案) | [`ci-cd.md`](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 启动之前运行:
|
|
> ```bash
|
|
> 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`。
|
|
>
|
|
> **体检与修复**(迁移后 / 恢复后建议各跑一次):
|
|
> ```bash
|
|
> 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`(只读挂载不影响权限检查!), 启动时就报:
|
|
> ```text
|
|
> [F] processStartupTemplateError() Gitea can't run with template errors:
|
|
> open home.tmpl: permission denied
|
|
> ```
|
|
> 容器 `Restarting` 死循环。**预览环境不会暴露这个问题** —— 预览容器用 `PREVIEW_UID`
|
|
> (默认宿主 uid 1001), 恰好就是文件属主, 所以 600 也读得到。
|
|
> ```bash
|
|
> # 体检: 容器用户能否读到
|
|
> 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
|
|
> 不够, 必须让容器重新生成一次:
|
|
> ```bash
|
|
> 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 '*'`; 手工验证时也要加:
|
|
> ```bash
|
|
> 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 失败:
|
|
> ```text
|
|
> 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 入口是否还通:
|
|
> ```bash
|
|
> 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` 在部署前检查三个目录存在且**可写**,
|
|
> 不满足就明确报错。若已经中招:
|
|
> ```bash
|
|
> sudo rm -rf customization/custom/options # 空的 root 目录, 删掉即可
|
|
> ```
|
|
>
|
|
> **⚠️ 8. `docker.sock` 怎么挂:`docker_host: "-"` 与"job 自己申报"是配套的一对。**
|
|
> 默认行为是 act_runner 把 docker daemon socket **自动**挂进 job 容器 —— 等于这个 runner 上的
|
|
> **每个** job 都白拿 docker(= root 等价)。现在把这份能力收窄成"要用 docker 的 job 自己申报":
|
|
> ```yaml
|
|
> # deploy/runner/config.yaml —— runner 侧: 不自动挂, 并给申报加白名单
|
|
> container:
|
|
> docker_host: "-" # 自动找 daemon, 但不挂进 job 容器
|
|
> valid_volumes: [...] # job 申报的挂载必须在这个表里
|
|
> ```
|
|
> ```yaml
|
|
> # .gitea/workflows/deploy.yml —— job 侧: 只给需要它的那个 job
|
|
> container:
|
|
> volumes:
|
|
> - /var/run/docker.sock:/var/run/docker.sock
|
|
> ```
|
|
> ⚠️ **两者必须成对**: 只写 `volumes` 而没有 `docker_host: "-"`, 就会和自动挂载撞成
|
|
> ```
|
|
> failed to create container: 'Duplicate mount point: /var/run/docker.sock'
|
|
> ```
|
|
> (2026-09-13 用 `act_runner exec` 预演时第一次踩到。注意 `exec` 有自己的
|
|
> `--container-daemon-socket` 默认值、**不读**配置里的 `docker_host`, 所以用 exec 预演时
|
|
> 这个错会一直出现 —— 它验证不了这一项。)
|
|
>
|
|
> **⚠️ 10. `valid_volumes` 会静默丢掉挂载。**
|
|
> job 申报的 `container.volumes`(以及全局 `options` 里的 `--volume`)都必须出现在
|
|
> `container.valid_volumes` 里, 否则 act_runner 只打一行
|
|
> `... is not a valid volume, will be ignored` 就把它丢掉, **job 照常往下跑** —— 现象是容器里
|
|
> 少了个目录, 而不是报错。2026-09-21 就因此让部署 job 的
|
|
> `cd /home/ymy/deploy/tjhlp-gitea` 失败。排查两行命令:
|
|
> ```bash
|
|
> docker exec gitea-runner sed -n '/valid_volumes/,+6p' /config/config.yaml
|
|
> docker inspect $(docker ps -q --filter name=GITEA-ACTIONS) \
|
|
> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'
|
|
> ```
|
|
>
|
|
> **⚠️ 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
|
|
|
|
```bash
|
|
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` 步骤注入代理参数 |
|
|
|
|
```bash
|
|
# 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`
|
|
|
|
```bash
|
|
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 内置默认值 |
|
|
|
|
```bash
|
|
# 生成密钥
|
|
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):
|
|
|
|
```bash
|
|
docker compose config --quiet && echo "compose 插值 OK"
|
|
docker compose config | grep -E 'APP_NAME|ALLOWED_HOST|image:' # 抽查关键项
|
|
```
|
|
|
|
### 4.5 启动
|
|
|
|
```bash
|
|
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 验证
|
|
|
|
```bash
|
|
sudo ./scripts/verify.sh
|
|
```
|
|
|
|
检查: 两个容器 `healthy`、`/api/healthz` 200、`/api/v1/version` 版本正确、经 Apache `/QA` 200。
|
|
站点名与登录源可以单独确认:
|
|
|
|
```bash
|
|
curl -sS --noproxy '*' http://127.0.0.1:2080/user/login | grep -o '<title>[^<]*</title>'
|
|
# 期望: <title>Sign In - 你的站点名</title>
|
|
```
|
|
|
|
locale 是否真的生效:
|
|
|
|
```bash
|
|
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, 从外部**完全看不出来**。
|
|
|
|
```bash
|
|
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`, 那等于没限制):
|
|
|
|
```bash
|
|
# /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. 备份
|
|
|
|
```bash
|
|
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 一致快照):
|
|
|
|
```bash
|
|
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. 恢复
|
|
|
|
```bash
|
|
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. 打印数据目录的回退命令。
|
|
|
|
脚本失败或恢复错了, 按它打印的命令回退:
|
|
|
|
```bash
|
|
sudo docker compose stop gitea
|
|
sudo rm -rf /srv/gitea && sudo mv /srv/gitea.pre-restore-<时间戳> /srv/gitea
|
|
sudo docker compose start gitea
|
|
```
|
|
|
|
**手工等价的恢复命令**(脚本不可用时):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 兼容。
|
|
|
|
```bash
|
|
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` 的产物跨大版本可读, 这条路最稳:
|
|
|
|
```bash
|
|
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. 日常运维
|
|
|
|
```bash
|
|
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` 之后:
|
|
|
|
```bash
|
|
docker compose up -d # 增量生效(必要时 --force-recreate)
|
|
```
|
|
|
|
改了**只由模板渲染**的键(如 `GITEA_APP_NAME`)则要重建 `app.ini`, 见陷阱 3。
|
|
|
|
---
|
|
|
|
## 9. 回滚
|
|
|
|
**回滚到宿主二进制部署**(源数据与源库都还在原地, 迁移只复制不移动):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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 密码与既有数据不一致 |
|
|
| CI 部署"成功"但页面还是旧模板 / 部署回滚 | `ci-cd.md` §5.2 | `custom/` 变了却没重启容器(或挂载源目录被换过 inode), 见该节说明 |
|
|
| `/QA/assets/...` 下自己放的静态文件 404 | — | 挂载的 `custom/public` 目录被删除重建过, `docker compose restart gitea` 重新挂载 |
|
|
|
|
---
|
|
|
|
## 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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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 反代
|
|
```
|
|
|
|
常用命令:
|
|
|
|
```bash
|
|
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` 验一次)。
|