HangmanLab.Server.T0/logs/VPS_GIT_WORKLOG_2026-03-20.md

vps.git 工作日志（2026-03-20）

记录人：晨曦 / Orion 范围：今天在 vps.git 上执行的排查、迁移、升级与清理操作 说明：本日志按实际执行顺序整理，便于后续审计、回顾与回滚分析。

---

1. 迁移前探测与现状确认

对 vps.git 做了只读探测，确认了原始部署情况：

• 宿主机为 Ubuntu 24.04.1 LTS
• 原先运行的裸机服务：
  • nginx
  • gitea.service
  • keycloak.service
  • mysql.service
• 原始端口/流量结构：
  • nginx 对外提供 80/443
  • gitea 裸机监听 3000，由 nginx 反代
  • keycloak 裸机监听 8443，由 nginx 反代
  • mysql 裸机监听 localhost:3306
• 原始数据位置：
  • Gitea 配置：/etc/gitea/app.ini
  • Gitea 数据：/var/lib/gitea
  • Keycloak 配置：/opt/keycloak/conf/keycloak.conf
  • Keycloak H2 数据：/opt/keycloak/data/h2
  • MySQL 数据：/var/lib/mysql
• 原始版本：
  • Gitea 1.22.4
  • Keycloak 26.0.6
  • MySQL 8.0.45

同时确认：

• Git over SSH 当前无人使用
• Gitea 与 Keycloak 均通过域名正常对外暴露
• Keycloak 的 Hangman-Lab realm 为后续重点保留对象

---

2. 迁移方案设计与落盘

在 workspace 中编写并落盘了以下迁移材料：

• VPS_GIT_DOCKER_MIGRATION_PLAN.md
• VPS_GIT_DOCKER_COMPOSE_DRAFT.yaml
• VPS_GIT_DOCKER_ENV_TEMPLATE.env
• VPS_GIT_DOCKER_MIGRATION_CHECKLIST.md
• VPS_GIT_DOCKER_MYSQL_INIT_DRAFT.sh

这些材料覆盖了：

• Docker 化目标架构
• compose 草案
• .env 模板
• MySQL 初始化逻辑
• 实施顺序与回滚顺序
• 验证点与风险点

---

3. 在 vps.git 上安装 Docker 环境

执行了 Docker 环境准备：

• 安装 Docker Engine
• 安装 Docker Compose Plugin
• 验证 docker --version 与 docker compose version

然后创建了部署目录：

• /root/git-kc
• /root/git-kc/backups
• /root/git-kc/docs
• /root/git-kc/gitea
• /root/git-kc/keycloak/import
• /root/git-kc/mysql/data
• /root/git-kc/mysql/init

并把 workspace 里的草案文件同步到 vps.git。

---

4. 生成部署配置与准备 Gitea 容器配置

在 vps.git 上：

• 根据模板生成了 /root/git-kc/.env
• 为 MySQL root、Gitea DB、Keycloak DB、Keycloak bootstrap admin 生成了随机密码
• 将宿主机 git 用户的真实 UID/GID 写入 .env

复制并调整了 Gitea 配置：

• /etc/gitea/app.ini → /root/git-kc/gitea/app.ini
• 将 Gitea 的数据库地址改为：mysql:3306
• 将 Gitea DB 密码改为 Docker MySQL 内的新密码
• 明确关闭了第一阶段的 Git over SSH：
  • DISABLE_SSH = true
  • START_SSH_SERVER = false

同时对 compose 做了兼容修正，使 Gitea 尽量贴近旧裸机布局：

• HOME=/home/git
• GITEA_WORK_DIR=/var/lib/gitea
• GITEA_CUSTOM=/var/lib/gitea/custom
• 额外挂载 /home/git:/home/git
• 显式使用宿主机 git 用户 UID/GID 运行容器

---

5. 迁移前备份

执行了迁移专用备份：

• 备份了 Gitea 配置
• 备份了 nginx 相关站点配置
• 导出了 Gitea MySQL 数据库 <gitea_db>
• 停止旧 Keycloak 后，导出了 Keycloak realm / users 到目录文件

Keycloak 导出文件位于：

• /root/git-kc/keycloak/import/

同时保留了升级前的 SQL dump 与 compose / env / app.ini 备份。

---

6. 启动 Docker MySQL 并迁移 Gitea 数据库

执行了 MySQL Docker 化：

• 启动 Docker MySQL 容器
• 首次启动时通过 01-init-databases.sh 自动创建：
  • <gitea_db>
  • <keycloak_db>
  • gitea@'%'
  • keycloak@'%'
• 将原始 Gitea 数据库导入 Docker MySQL

导入后核对了核心数据：

• users = 8
• repos = 72
• • external_login_user = 7

确认 Gitea 业务主数据迁移成功。

---

7. Keycloak H2 → MySQL 迁移与导入问题修复

7.1 初次导入失败原因

Keycloak 首次导入失败，定位到：

• Hangman-Lab realm 中存在 JS policy
• 报错：Script upload is disabled

进一步确认：

• 不是整个 authorizationSettings 无法导入
• 而是其中 type = "js" 的 policy 被新版本 Keycloak 导入路径拒绝

具体涉及的 client：

• gitea
• iredmail
• youtrack-dev

脚本内容实际都是同一段默认放行模板：

// by default, grants any permission associated with this policy
$evaluation.grant();

7.2 最小修补

经确认后，执行了最小修补方案：

• 移除 gitea client 的 authorizationSettings
• 彻底移除已废弃 client：
  • iredmail
  • youtrack-dev
• 同时移除它们的残留引用：
  • client role definitions
  • service-account 用户
  • 相关 client role 映射

修补仅发生在迁移使用的导出文件中：

• /root/git-kc/keycloak/import/Hangman-Lab-realm.json

7.3 导入成功

随后：

• 重建 <keycloak_db>
• 重新导入 master / Hangman-Lab / Dialectic
• 启动 Docker Keycloak 成功
• 确认 discovery 文档正常，issuer 正常

并在导入完成后：

• 去掉了 compose 中的一次性 --import-realm
• 去掉了临时加入的 KC_FEATURES=scripts

确保后续 Keycloak 重启不会重复导入。

---

8. Gitea Docker 切换与启动修复

Gitea 初次容器启动失败，原因是：

• 容器以 root 身份运行
• Gitea 拒绝以 root 启动

修复措施：

• 在 compose 中显式设置：
  • user: "${GITEA_UID}:${GITEA_GID}"

调整后：

• Gitea 容器成功启动
• 健康检查正常
• 通过 nginx 暴露的 Gitea 页面可访问
• Gitea 的 OIDC 登录入口可正确跳转至 Keycloak

---

9. nginx 切换

保留宿主机 nginx 架构不变，仅修改 Keycloak upstream：

• 从：https://localhost:8443
• 改为：http://localhost:8080

操作后：

• 执行 nginx -t
• reload nginx
• 验证 login.hangman-lab.top discovery 正常
• 验证 git.hangman-lab.top 仍正常

---

10. 裸机部署清理

在确认 Docker 版跑通后，删除了旧裸机部署：

已删除

• Gitea 裸机：
  • gitea.service
  • /usr/local/bin/gitea
  • /etc/gitea
• Keycloak 裸机：
  • keycloak.service
  • /etc/default/keycloak
  • /opt/keycloak
• MySQL 裸机：
  • mysql.service
  • 旧 MySQL 包
  • /var/lib/mysql
  • /etc/mysql

保留

保留了以下正在被 Docker 使用的宿主机路径：

• /var/lib/gitea
• /home/git

原因：

• 这两者属于 Docker Gitea 当前的 live 挂载目录，不是旧垃圾。

---

11. 升级到最新版本

在 Docker 迁移稳定后，继续升级到了当时的最新版本，并保持固定版本写死：

Gitea

• 从：1.22.4
• 升级到：1.25.5

验证：

• 容器健康正常
• 页面访问正常
• OIDC 跳转正常

Keycloak

• 从：26.0.6
• 升级到：26.5.6

Keycloak 升级期间自动执行了数据库 model migration，日志中可见：

• Hangman-Lab migrated to 26.1.0 / 26.2.0 / 26.3.0 / 26.4.0 / 26.4.3

升级完成后验证：

• 容器健康正常
• discovery 正常
• issuer 正常
• Gitea OIDC 跳转正常

升级前备份保存在：

• /root/git-kc/backups/upgrade-2026-03-20-151958/

包含：

• <gitea_db>.sql
• <keycloak_db>.sql
• compose.yaml.bak
• .env.bak
• app.ini.bak

---

12. 磁盘清理与空间回收

后续又做了宿主机空间清理：

journald

• 将 /var/log/journal 限制到 300MB
• 实际回收后 journald 占用约 252.9MB

Docker 旧镜像

删除了未使用的旧镜像：

• gitea/gitea:1.22.4
• quay.io/keycloak/keycloak:26.0.6

APT

• 按要求保留了 apt 元数据和缓存
• 同时检查了 apt-get -s autoremove
• 当前无明显可自动移除的孤儿包

---

13. 当前最终状态（截至日志记录时）

Docker 正在运行的服务：

• mysql:8.0.45
• gitea/gitea:1.25.5
• quay.io/keycloak/keycloak:26.5.6

验证通过项：

• https://git.hangman-lab.top/ 可访问
• https://login.hangman-lab.top/ 可访问
• https://login.hangman-lab.top/realms/Hangman-Lab/.well-known/openid-configuration 可访问
• Gitea 的 OIDC 登录入口会正确跳转至 Keycloak

当时磁盘空间大致为：

• 总盘：23G
• 已用：12G
• 可用：11G
• 使用率：约 53%

---

14. 本次迁移中对业务配置做过的显式变更

这是后续最需要知道的一部分：

1. Gitea 第一阶段明确关闭了 Git over SSH

   • DISABLE_SSH = true
   • START_SSH_SERVER = false

2. Keycloak 导入时对 Hangman-Lab realm 做了最小修补

   • 移除了 gitea 的 authorizationSettings
   • 删除了已废弃 client：
     • iredmail
     • youtrack-dev
   • 同时删除了它们关联的 service-account / client role 引用

3. nginx Keycloak upstream 已改为宿主机本地 HTTP 反代

   • http://localhost:8080

---

15. 后续建议

• 用浏览器人工完成一次 Gitea → Keycloak SSO 登录验收
• 用实际仓库完成一次 HTTPS clone / push 验收
• 如未来要恢复 Git over SSH，再单独设计第二阶段方案
• 如要继续精简磁盘，可再评估 apt 元数据清理，但本次按要求保留

---

结论

今天在 vps.git 上完成了：

• 裸机 Gitea / Keycloak / MySQL → Docker 迁移
• Keycloak H2 → MySQL 迁移
• Gitea / Keycloak 升级到当时最新版本
• 旧裸机部署清理
• journald 限额与旧镜像清理

当前服务已切换为 Docker 运行，并完成了基础联通验证。