orion/HangmanLab.Server.T0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
HangmanLab.Server.T0/git-kc/docs/CHECKLIST.md

9.4 KiB
Raw Permalink Blame History

vps.git Docker 迁移 Checklist

目标：将 vps.git 上的 Gitea、Keycloak、MySQL 迁移到 Docker；宿主机 nginx 保持不动。

当前约束：

  • Gitea / Keycloak / MySQL 进入同一个 Docker 网络
  • MySQL 为单实例，内部拆分 <gitea_db> / <keycloak_db>
  • Gitea 直接挂载旧目录
  • Keycloak 从 H2 迁移到 MySQL
  • 本次先不启用 Git over SSH

0. 迁移前确认

  • 确认维护窗口可开始
  • 确认当前整机备份已存在
  • 确认当前无人依赖 Git over SSH
  • 确认本次不做大版本升级
  • 确认宿主机 nginx 保持不动

1. 安装 Docker Engine（vps.git）

推荐使用 Docker 官方仓库安装。

apt-get update
apt-get install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

docker --version
docker compose version

验收：

  • docker --version 正常
  • docker compose version 正常

2. 准备部署目录

mkdir -p ~/git-kc/{backups,docs,gitea,keycloak/import,mysql/data,mysql/init}
chmod 700 ~/git-kc

验收：

  • ~/git-kc 已创建
  • 子目录结构完整

3. 准备 compose 与 .env

将以下草案文件放到目标目录：

  • compose.yaml
  • .env

来源建议：

  • 使用 workspace 内草案：
    • VPS_GIT_DOCKER_COMPOSE_DRAFT.yaml
    • VPS_GIT_DOCKER_ENV_TEMPLATE.env
cp VPS_GIT_DOCKER_COMPOSE_DRAFT.yaml ~/git-kc/compose.yaml
cp VPS_GIT_DOCKER_ENV_TEMPLATE.env ~/git-kc/.env
chmod 600 ~/git-kc/.env

然后填写真实密码，并把 GITEA_UID/GITEA_GID 改成宿主机 git 用户实际数值：

id -u git
id -g git

验收：

  • ~/git-kc/compose.yaml 已就位
  • ~/git-kc/.env 已填写真实密码
  • GITEA_UID/GITEA_GID 已按实际值修正

4. 准备 Gitea 配置副本

复制现有配置，不直接原地改 /etc/gitea/app.ini。

cp /etc/gitea/app.ini ~/git-kc/gitea/app.ini

需要修改的核心项：

  • [database] HOST = mysql:3306
  • 保持 DB_TYPE = mysql
  • NAME = <gitea_db>
  • USER = gitea
  • PASSWD = <新的 Docker MySQL 中 gitea 用户密码>
  • 保持 ROOT_URL = https://git.hangman-lab.top/
  • 本次先不启用 Git over SSH
  • 在 app.ini 中显式设置 DISABLE_SSH = true
  • 如存在 START_SSH_SERVER，显式设置为 false
  • 检查页面不再误导用户展示不可用的 SSH clone/push 路径

建议先备份副本再改：

cp ~/git-kc/gitea/app.ini ~/git-kc/gitea/app.ini.bak

验收：

  • ~/git-kc/gitea/app.ini 已生成
  • DB HOST 已改为 mysql:3306
  • 其他核心业务配置未误改

5. 准备 MySQL 初始化逻辑

目标：Docker MySQL 首次启动时自动创建：

  • <gitea_db>
  • <keycloak_db>
  • gitea@'%'
  • keycloak@'%'

建议在 ~/git-kc/mysql/init/ 中放一个首次初始化脚本，例如：

  • 01-init-databases.sh

workspace 内已提供草案文件：

  • VPS_GIT_DOCKER_MYSQL_INIT_DRAFT.sh

可直接放到目标位置：

cp VPS_GIT_DOCKER_MYSQL_INIT_DRAFT.sh ~/git-kc/mysql/init/01-init-databases.sh
chmod 755 ~/git-kc/mysql/init/01-init-databases.sh

如果实施环境不是当前 workspace 所在机器，也需要先把该草案文件同步到 vps.git。

脚本职责：

  • 读取 .env 中的变量
  • 创建两个 database
  • 创建两个用户
  • 分配最小权限

注意：docker-entrypoint-initdb.d 只会在 空 datadir 第一次启动 时执行。

验收：

  • 已准备初始化脚本或确认采用手动 SQL 初始化

6. 准备 Keycloak 导出目录

mkdir -p ~/git-kc/keycloak/import

说明：

  • 旧 Keycloak 导出的 realm 文件，后续放到这里
  • Docker Keycloak 首次启动时通过 --import-realm 导入

验收：

  • ~/git-kc/keycloak/import 已存在

7. 预拉取镜像（切换前）

cd ~/git-kc
docker compose --env-file .env pull

验收：

  • MySQL 镜像拉取成功
  • Gitea 镜像拉取成功
  • Keycloak 镜像拉取成功

8. 迁移前备份

8.1 备份 Gitea 配置

cp /etc/gitea/app.ini ~/git-kc/backups/app.ini.$(date +%F-%H%M%S).bak
  • 已备份 /etc/gitea/app.ini

8.2 导出 Gitea 数据库

mysqldump \
  --single-transaction \
  --routines \
  --triggers \
  --events \
  <gitea_db> > ~/git-kc/backups/<gitea_db>.$(date +%F-%H%M%S).sql
  • 已导出 <gitea_db>

8.3 导出 Keycloak（H2）

先停止旧 Keycloak，再执行离线导出：

systemctl stop keycloak
sudo -u keycloak /opt/keycloak/bin/kc.sh export \
  --dir ~/git-kc/keycloak/import \
  --users realm_file

如果导出目录权限有问题，可先导出到 /tmp 或 keycloak 用户可写目录，再移动到 ~/git-kc/keycloak/import/。

  • 已导出 Keycloak realm / users

8.4 备份 nginx 相关配置

cp /etc/nginx/sites-enabled/git.hangman-lab.top ~/git-kc/backups/git.hangman-lab.top.$(date +%F-%H%M%S).bak
cp /etc/nginx/sites-enabled/login.hangman-lab.top ~/git-kc/backups/login.hangman-lab.top.$(date +%F-%H%M%S).bak
  • 已备份 nginx 站点配置

9. 切换阶段

9.1 停止旧服务

systemctl stop gitea
systemctl stop keycloak
systemctl stop mysql
  • 旧 Gitea 已停
  • 旧 Keycloak 已停
  • 旧 MySQL 已停

9.2 启动 Docker MySQL

cd ~/git-kc
docker compose --env-file .env up -d mysql
docker compose ps
  • MySQL 容器已启动
  • MySQL healthcheck 正常

9.3 初始化数据库

如果已准备 mysql/init 初始化脚本：

  • 确认第一次启动已执行成功

如果采用手动方式，执行 SQL 初始化：

docker exec -it git-kc-mysql mysql -uroot -p

手动创建：

  • <gitea_db>
  • <keycloak_db>
  • gitea 用户及权限
  • keycloak 用户及权限

9.4 导入 Gitea 数据库

cat ~/git-kc/backups/<gitea_db>.<timestamp>.sql | docker exec -i git-kc-mysql mysql -uroot -p${MYSQL_ROOT_PASSWORD} <gitea_db>
  • <gitea_db> 已导入

9.5 启动 Docker Keycloak

cd ~/git-kc
docker compose --env-file .env up -d keycloak
docker compose logs --tail=200 keycloak
  • Keycloak 容器已启动
  • import 完成
  • 无明显启动报错

9.6 启动 Docker Gitea

cd ~/git-kc
docker compose --env-file .env up -d gitea
docker compose logs --tail=200 gitea
  • Gitea 容器已启动
  • 无明显启动报错

10. 修改 nginx（仅 Keycloak upstream）

目标变更：

  • 从 proxy_pass https://localhost:8443;
  • 改为 proxy_pass http://localhost:8080;

同时确认保留：

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

验证并重载：

nginx -t
systemctl reload nginx
  • nginx 配置校验通过
  • nginx 已 reload

11. 验证阶段

11.1 验证 Gitea

  • https://git.hangman-lab.top/ 可访问
  • 首页正常
  • 用户可登录
  • 仓库列表正常
  • 现有仓库可见
  • HTTPS clone 正常
  • HTTPS push 正常
  • OIDC 跳转到 Keycloak 正常
  • 从 Keycloak 回跳 Gitea 正常

11.2 验证 Keycloak

  • https://login.hangman-lab.top/ 可访问
  • /.well-known/openid-configuration 正常
  • Hangman-Lab realm 正常
  • 管理后台可登录
  • 普通用户可登录
  • 原 client 保留
  • issuer 与原来一致

11.3 验证 MySQL

  • <gitea_db> 表完整
  • <keycloak_db> 表完整
  • Gitea 能正常连接 MySQL
  • Keycloak 能正常连接 MySQL

11.4 验证 Docker 重启持久化

docker compose --env-file ~/git-kc/.env -f ~/git-kc/compose.yaml restart
  • 三个容器重启后仍正常
  • 数据未丢失

12. 回滚 Checklist

如果验证失败，执行回滚：

12.1 停止 Docker 服务

cd ~/git-kc
docker compose --env-file .env down
  • Docker 容器已停

12.2 恢复 nginx Keycloak upstream

  • 将 http://localhost:8080 改回 https://localhost:8443
nginx -t
systemctl reload nginx
  • nginx 已恢复

12.3 启动旧宿主机服务

systemctl start mysql
systemctl start keycloak
systemctl start gitea
  • 旧 MySQL 已恢复
  • 旧 Keycloak 已恢复
  • 旧 Gitea 已恢复

12.4 回滚验证

  • Gitea 页面恢复
  • Keycloak 页面恢复
  • Gitea 登录恢复
  • OIDC 恢复

13. 迁移后待办（非本次切换阻塞项）

  • 清理 Keycloak 首次导入相关临时文件
  • 视情况去掉 Keycloak --import-realm
  • 评估是否恢复 Git over SSH
  • 如需恢复 Git over SSH，单独设计第二阶段方案
  • 更新与 Docker 化相关的运维脚本 <0A><>第二阶段方案
  • 更新与 Docker 化相关的运维脚本 <0A>案
  • 更新与 Docker 化相关的运维脚本
Reference in New Issue View Git Blame Copy Permalink