# 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 化相关的运维脚本
��第二阶段方案
- [ ] 更新与 Docker 化相关的运维脚本
�案
- [ ] 更新与 Docker 化相关的运维脚本