448 lines
9.4 KiB
Markdown
448 lines
9.4 KiB
Markdown
# 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 官方仓库安装。
|
||
|
||
```bash
|
||
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. 准备部署目录
|
||
|
||
```bash
|
||
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`
|
||
|
||
```bash
|
||
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` 用户实际数值：
|
||
|
||
```bash
|
||
id -u git
|
||
id -g git
|
||
```
|
||
|
||
验收：
|
||
- [ ] `~/git-kc/compose.yaml` 已就位
|
||
- [ ] `~/git-kc/.env` 已填写真实密码
|
||
- [ ] `GITEA_UID/GITEA_GID` 已按实际值修正
|
||
|
||
---
|
||
|
||
## 4. 准备 Gitea 配置副本
|
||
|
||
复制现有配置，不直接原地改 `/etc/gitea/app.ini`。
|
||
|
||
```bash
|
||
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 路径
|
||
|
||
建议先备份副本再改：
|
||
|
||
```bash
|
||
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`
|
||
|
||
可直接放到目标位置：
|
||
|
||
```bash
|
||
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 导出目录
|
||
|
||
```bash
|
||
mkdir -p ~/git-kc/keycloak/import
|
||
```
|
||
|
||
说明：
|
||
- 旧 Keycloak 导出的 realm 文件，后续放到这里
|
||
- Docker Keycloak 首次启动时通过 `--import-realm` 导入
|
||
|
||
验收：
|
||
- [ ] `~/git-kc/keycloak/import` 已存在
|
||
|
||
---
|
||
|
||
## 7. 预拉取镜像（切换前）
|
||
|
||
```bash
|
||
cd ~/git-kc
|
||
docker compose --env-file .env pull
|
||
```
|
||
|
||
验收：
|
||
- [ ] MySQL 镜像拉取成功
|
||
- [ ] Gitea 镜像拉取成功
|
||
- [ ] Keycloak 镜像拉取成功
|
||
|
||
---
|
||
|
||
## 8. 迁移前备份
|
||
|
||
### 8.1 备份 Gitea 配置
|
||
|
||
```bash
|
||
cp /etc/gitea/app.ini ~/git-kc/backups/app.ini.$(date +%F-%H%M%S).bak
|
||
```
|
||
|
||
- [ ] 已备份 `/etc/gitea/app.ini`
|
||
|
||
### 8.2 导出 Gitea 数据库
|
||
|
||
```bash
|
||
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，再执行离线导出：
|
||
|
||
```bash
|
||
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 相关配置
|
||
|
||
```bash
|
||
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 停止旧服务
|
||
|
||
```bash
|
||
systemctl stop gitea
|
||
systemctl stop keycloak
|
||
systemctl stop mysql
|
||
```
|
||
|
||
- [ ] 旧 Gitea 已停
|
||
- [ ] 旧 Keycloak 已停
|
||
- [ ] 旧 MySQL 已停
|
||
|
||
### 9.2 启动 Docker MySQL
|
||
|
||
```bash
|
||
cd ~/git-kc
|
||
docker compose --env-file .env up -d mysql
|
||
docker compose ps
|
||
```
|
||
|
||
- [ ] MySQL 容器已启动
|
||
- [ ] MySQL healthcheck 正常
|
||
|
||
### 9.3 初始化数据库
|
||
|
||
如果已准备 `mysql/init` 初始化脚本：
|
||
- [ ] 确认第一次启动已执行成功
|
||
|
||
如果采用手动方式，执行 SQL 初始化：
|
||
|
||
```bash
|
||
docker exec -it git-kc-mysql mysql -uroot -p
|
||
```
|
||
|
||
手动创建：
|
||
- [ ] `<gitea_db>`
|
||
- [ ] `<keycloak_db>`
|
||
- [ ] `gitea` 用户及权限
|
||
- [ ] `keycloak` 用户及权限
|
||
|
||
### 9.4 导入 Gitea 数据库
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cd ~/git-kc
|
||
docker compose --env-file .env up -d keycloak
|
||
docker compose logs --tail=200 keycloak
|
||
```
|
||
|
||
- [ ] Keycloak 容器已启动
|
||
- [ ] import 完成
|
||
- [ ] 无明显启动报错
|
||
|
||
### 9.6 启动 Docker Gitea
|
||
|
||
```bash
|
||
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;`
|
||
|
||
验证并重载：
|
||
|
||
```bash
|
||
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 重启持久化
|
||
|
||
```bash
|
||
docker compose --env-file ~/git-kc/.env -f ~/git-kc/compose.yaml restart
|
||
```
|
||
|
||
- [ ] 三个容器重启后仍正常
|
||
- [ ] 数据未丢失
|
||
|
||
---
|
||
|
||
## 12. 回滚 Checklist
|
||
|
||
如果验证失败，执行回滚：
|
||
|
||
### 12.1 停止 Docker 服务
|
||
|
||
```bash
|
||
cd ~/git-kc
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
- [ ] Docker 容器已停
|
||
|
||
### 12.2 恢复 nginx Keycloak upstream
|
||
|
||
- [ ] 将 `http://localhost:8080` 改回 `https://localhost:8443`
|
||
|
||
```bash
|
||
nginx -t
|
||
systemctl reload nginx
|
||
```
|
||
|
||
- [ ] nginx 已恢复
|
||
|
||
### 12.3 启动旧宿主机服务
|
||
|
||
```bash
|
||
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 化相关的运维脚本
|
||
<EFBFBD><EFBFBD>第二阶段方案
|
||
- [ ] 更新与 Docker 化相关的运维脚本
|
||
<EFBFBD>案
|
||
- [ ] 更新与 Docker 化相关的运维脚本
|