XuqmGroup-PrivateDeploy/docs/runbook.md

私有化部署运行手册

一键部署

curl -fsSL https://xuqinmin.com/xuqmGroup/XuqmGroup-PrivateDeploy/raw/branch/main/install.sh \
  -o install.sh && bash install.sh

交互式向导依次完成：

1. 选择租户初始化方式（新建 / 迁移）
2. 填写租户信息或迁移密钥
3. 填写外部访问地址（宿主机 nginx 对外的地址，用于 SDK 配置）
4. 自动完成容器启动、数据库初始化、全量验证

完成后按输出的端口表配置宿主机 nginx。

---

Nginx 配置

部署完成后，将以下 location 块加入宿主机 nginx 的 server 配置：

charset utf-8;
client_max_body_size 100m;

location /api/v1/updates/ { proxy_pass http://127.0.0.1:11229/api/v1/updates/; }
location /api/v1/rn/      { proxy_pass http://127.0.0.1:11229/api/v1/rn/; }
location /api/im/         { proxy_pass http://127.0.0.1:11228/api/im/; }
location /ws/im {
    proxy_pass http://127.0.0.1:11228/ws/im;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}
location /api/license/    { proxy_pass http://127.0.0.1:11231/api/license/; }
location /file/ {
    proxy_pass http://127.0.0.1:11225/file/;
    client_max_body_size 500m;
    proxy_read_timeout 300s;
}
location /api/            { proxy_pass http://127.0.0.1:11224/api/; }
location /actuator/       { proxy_pass http://127.0.0.1:11224/actuator/; }
location /ops             { proxy_pass http://127.0.0.1:11227; }
location /                { proxy_pass http://127.0.0.1:11226; }

location 顺序不可颠倒：精确路径（/api/im/、/api/v1/、/api/license/）必须在通用路径（/api/）前面。

---

端口对照表

宿主机端口	服务	容器内端口	说明
11224	tenant-service	9001	核心 API
11225	file-service	8086	文件上传下载
11226	tenant-web	80	控制台前端
11227	ops-web	80	运营后台前端
11228	im-service	8082	IM HTTP + WebSocket
11229	update-service	8084	版本管理 + RN 热更新
11230	license-service	8085	License 校验
11231	push-service	8083	厂商推送

所有端口绑定 127.0.0.1，外部不可直接访问。

---

租户迁移

迁移通过一键部署向导完成，选择「迁移租户」后：

1. 前往公有化平台控制台 → 安全中心 → 私有化部署迁移 → 生成迁移密钥
2. 将 pmk_ 开头的密钥粘贴进向导
3. 脚本自动导出租户数据、导入私有库、写入 license 记录、重启服务

迁移为单租户操作，会清空现有 bootstrap 数据后写入迁移数据。

---

常用运维命令

# 查看所有容器状态
docker compose -f docker-compose.yml -f docker-compose.infra.yml ps

# 查看服务日志
docker compose -f docker-compose.yml -f docker-compose.infra.yml logs --tail 100 tenant-service

# 重新运行全量验证
bash scripts/verify.sh

# 停止所有服务（保留数据）
docker compose -f docker-compose.yml -f docker-compose.infra.yml down

# 启用可选服务
bash scripts/enable-service.sh im

# 禁用可选服务（不删数据）
bash scripts/disable-service.sh im

# 备份数据
bash scripts/backup.sh

# 恢复数据
bash scripts/restore.sh <backup-file>

---

数据目录

路径	说明
data/mysql/	MySQL 数据文件
data/redis/	Redis AOF 文件
data/uploads/	文件服务上传目录
data/update/	版本管理包存储
data/backups/	备份文件
logs/	审计日志

---

重新部署（幂等）

脚本幂等，可重复执行：

bash install.sh

已运行的容器不会被重建，数据目录不受影响。