docs: 拆分 README.md 为多个子文档，README 简化为架构引导大纲
This commit is contained in:
319
codes/agent/game-docker/docs/05-operations.md
Normal file
319
codes/agent/game-docker/docs/05-operations.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 常见运维操作
|
||||
|
||||
---
|
||||
|
||||
## 场景一：更换域名
|
||||
|
||||
当需要将服务迁移到新域名时（例如 `daoqijuyou.cn` → `newdomain.com`），只需改一个变量。
|
||||
|
||||
### 1. 修改 `.env` 中的 `ROOT_DOMAIN`
|
||||
|
||||
```bash
|
||||
vim .env
|
||||
```
|
||||
|
||||
```bash
|
||||
# 改成新父域名，三个子域名自动跟随
|
||||
ROOT_DOMAIN=newdomain.com
|
||||
```
|
||||
|
||||
`docker-compose.yml` 将自动推导：
|
||||
|
||||
| 推导变量 | 结果 |
|
||||
|---------|------|
|
||||
| `API_DOMAIN` | `api.newdomain.com` |
|
||||
| `DLWEB_DOMAIN` | `dlapi.newdomain.com` |
|
||||
| `SITE_API_URL` | `https://api.newdomain.com` |
|
||||
| `SITE_PAY_NOTIFY_URL` | `https://api.newdomain.com` |
|
||||
| `SITE_OPEN_URL` | `http://open.newdomain.com` |
|
||||
| `DLWEB_DL_API_V3_URL` | `https://dlapi.newdomain.com` |
|
||||
|
||||
> **子域名不符合标准规律时**，在 `.env` 中单独覆盖对应变量即可：
|
||||
> ```bash
|
||||
> DLWEB_DOMAIN=dl-manage.newdomain.com
|
||||
> ```
|
||||
|
||||
> **其他独立 URL 变量**（`DLWEB_SETTLE_URL`、`DLWEB_PROXY_URL`、`QQ_CALLBACK_URL` 等）仍需在 `.env` 中手动配置，详见 `.env.example` 中的注释。
|
||||
|
||||
### 2. DNS 解析
|
||||
|
||||
```bash
|
||||
# 验证 DNS 解析
|
||||
nslookup api.newdomain.com
|
||||
nslookup dlapi.newdomain.com
|
||||
```
|
||||
|
||||
### 3. 重新申请 SSL 证书
|
||||
|
||||
```bash
|
||||
./deploy.sh ssl-init --staging # 测试验证
|
||||
./deploy.sh ssl-init # 正式申请
|
||||
```
|
||||
|
||||
### 4. 重启所有服务
|
||||
|
||||
```bash
|
||||
./deploy.sh restart
|
||||
```
|
||||
|
||||
重启时自动完成：
|
||||
- Nginx 使用新域名的 `server_name` 和 SSL 证书
|
||||
- `docker-entrypoint.sh` 用新域名替换 JS/HTML 中的硬编码 URL
|
||||
- PHP `env()` 读取新的环境变量值
|
||||
|
||||
### 5. 更新微信后台配置
|
||||
|
||||
> **关键路由说明：** Nginx 在 `api.newdomain.com` 上配置了 `/wx/` 前缀路由——以 `/wx/` 开头的请求被反向代理到 wxserver（Node.js），其余请求仍由 PHP API 处理。
|
||||
|
||||
#### 5.1 微信小程序后台
|
||||
|
||||
> **入口：** [mp.weixin.qq.com](https://mp.weixin.qq.com) → 开发 → 开发管理 → 开发设置 → 服务器域名
|
||||
|
||||
| 配置项 | 新值 | 不更新时的现象 |
|
||||
|--------|------|--------------|
|
||||
| **request 合法域名** | `https://api.newdomain.com` | `wx.request` 报 `invalid url`，所有网络请求失败 |
|
||||
| **业务域名** | `api.newdomain.com` | web-view 提示"不在业务域名列表中" |
|
||||
|
||||
> 小程序域名配置每月只能修改 5 次，且每项域名必须已备案并启用 HTTPS。
|
||||
|
||||
#### 5.2 微信公众号后台
|
||||
|
||||
> **入口：** [mp.weixin.qq.com](https://mp.weixin.qq.com) → 设置与开发 → 公众号设置 → 功能设置
|
||||
|
||||
| 配置项 | 填写值 | 不更新时的现象 |
|
||||
|--------|--------|--------------|
|
||||
| 业务域名 | `api.newdomain.com` | 微信内置浏览器提示"域名不合法" |
|
||||
| 网页授权域名 | `api.newdomain.com` | 授权跳转被微信拦截，永久头像功能不可用 |
|
||||
| JS 接口安全域名 | `api.newdomain.com` | `wx.config()` 签名验证失败，微信支付按钮无法唤起 |
|
||||
|
||||
> **⚠️ 远程配置也需同步修改：** `WX_OA_REDIRECT_DOMAIN` 未配置时，wxserver 从远程配置文件读取 `minipro_api_url`。建议同步更新 Gitee Raw 配置 `minipro_api_url` 为 `api.newdomain.com/wx`。
|
||||
|
||||
#### 5.3 微信支付商户后台
|
||||
|
||||
> **入口：** [pay.weixin.qq.com](https://pay.weixin.qq.com) → 账户中心 → 商户信息 → 支付配置 → JSAPI 支付授权目录
|
||||
|
||||
| 配置值 | 用途 |
|
||||
|--------|------|
|
||||
| `https://api.newdomain.com/` | JSAPI 支付页面所在目录（必须包含末尾斜杠） |
|
||||
|
||||
不更新的后果：下单时提示"当前 URL 未注册"，JSAPI 支付彻底无法使用。
|
||||
|
||||
#### 配置清单汇总
|
||||
|
||||
| 平台 | 配置项 | 填写值 |
|
||||
|------|--------|--------|
|
||||
| 微信小程序后台 | request 合法域名 | `https://api.newdomain.com` |
|
||||
| 微信小程序后台 | 业务域名 | `api.newdomain.com` |
|
||||
| 微信公众号后台 | 业务域名 | `api.newdomain.com` |
|
||||
| 微信公众号后台 | 网页授权域名 | `api.newdomain.com` |
|
||||
| 微信公众号后台 | JS 接口安全域名 | `api.newdomain.com` |
|
||||
| 微信支付商户后台 | JSAPI 支付授权目录 | `https://api.newdomain.com/` |
|
||||
|
||||
---
|
||||
|
||||
## 场景二：更换数据库地址
|
||||
|
||||
当数据库实例迁移（例如 RDS 升级、切换区域）时：
|
||||
|
||||
### 1. 修改 `.env` 中对应的数据库变量
|
||||
|
||||
| 数据库 | 需修改的变量 | 使用者 |
|
||||
|--------|-------------|--------|
|
||||
| API 主库 | `API_DB_HOST`, `API_DB_PORT`, `API_DB_USER`, `API_DB_PASSWORD` | api 服务 |
|
||||
| 代理后台主库 | `DLWEB_DB_HOST`, `DLWEB_DB_PORT`, `DLWEB_DB_USER`, `DLWEB_DB_PASSWORD` | dlweb 服务 |
|
||||
| 代理后台从库 | `DLWEB_SLAVE_DB_HOST`, `DLWEB_SLAVE_DB_PORT`, `DLWEB_SLAVE_DB_USER`, `DLWEB_SLAVE_DB_PASSWORD` | dlweb 读操作 |
|
||||
| 外部游戏库 | `EXT_GAME_DB_HOST`, `EXT_GAME_DB_PORT`, `EXT_GAME_DB_USER`, `EXT_GAME_DB_PASSWORD` | Synchronize.php |
|
||||
| 战绩库 | `EXT_GRADE_DB_HOST`, `EXT_GRADE_DB_PORT`, `EXT_GRADE_DB_USER`, `EXT_GRADE_DB_PASSWORD` | game.php |
|
||||
| 开发库 | `EXT_DEV_DB_HOST`, `EXT_DEV_DB_PORT`, `EXT_DEV_DB_USER`, `EXT_DEV_DB_PASSWORD` | DEBUG 模式 |
|
||||
|
||||
### 2. 重启受影响的服务
|
||||
|
||||
```bash
|
||||
docker compose restart api # 只改了 API 数据库
|
||||
docker compose restart dlweb # 只改了 DLWEB 数据库
|
||||
docker compose restart dlweb syncjob cronjob # 改了外部游戏库
|
||||
./deploy.sh restart # 改了多个，全部重启
|
||||
```
|
||||
|
||||
### 3. 验证连接
|
||||
|
||||
```bash
|
||||
docker logs --tail 20 youle-api
|
||||
docker logs --tail 20 youle-dlweb
|
||||
docker logs --tail 10 youle-syncjob
|
||||
```
|
||||
|
||||
> 如果新数据库有 IP 白名单限制，需要将 Docker 宿主机的公网 IP 加入 RDS 白名单。
|
||||
|
||||
---
|
||||
|
||||
## 场景三：更换服务器（整体迁移）
|
||||
|
||||
### 1. 打包项目文件（旧服务器）
|
||||
|
||||
```bash
|
||||
cd /path/to/game-docker
|
||||
tar czf game-docker.tar.gz --exclude='.env' --exclude='game/' .
|
||||
```
|
||||
|
||||
### 2. 传输到新服务器
|
||||
|
||||
```bash
|
||||
scp game-docker.tar.gz newserver:/opt/
|
||||
```
|
||||
|
||||
### 3. 在新服务器上部署
|
||||
|
||||
```bash
|
||||
cd /opt
|
||||
tar xzf game-docker.tar.gz -C game-docker
|
||||
cd game-docker
|
||||
cp .env.example .env
|
||||
vim .env
|
||||
```
|
||||
|
||||
### 4. 确认修改项
|
||||
|
||||
| 检查项 | 是否需要改 | 说明 |
|
||||
|--------|-----------|------|
|
||||
| 域名（`*_DOMAIN`） | 域名不变则不改 | DNS 需指向新服务器 IP |
|
||||
| 数据库地址（`*_DB_HOST`） | 通常不改 | RDS 地址不变，但需将新服务器 IP 加入白名单 |
|
||||
| Redis 地址 | 不改 | Docker 内置 Redis，随容器迁移 |
|
||||
| 微信/支付配置 | 不改 | AppID/Secret 与服务器无关 |
|
||||
| 游戏服务器查询地址 | 看情况 | 游戏服务器也迁移了则需改 |
|
||||
| IP 白名单 | 可能需改 | `INTERNAL_WHITELIST` 加入新 IP |
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
```bash
|
||||
chmod +x deploy.sh init-ssl.sh
|
||||
./deploy.sh ssl-init # 新服务器需重新申请证书
|
||||
./deploy.sh up
|
||||
```
|
||||
|
||||
### 6. 验证所有服务
|
||||
|
||||
```bash
|
||||
./deploy.sh status
|
||||
curl -k https://api.yourdomain.com/
|
||||
curl -k https://dlapi.yourdomain.com/
|
||||
curl -k https://api.yourdomain.com/wx/api/login
|
||||
docker logs --tail 5 youle-syncjob
|
||||
docker logs --tail 5 youle-cronjob
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景四：更改 Redis 配置
|
||||
|
||||
```bash
|
||||
vim .env
|
||||
# 修改以下变量：
|
||||
# REDIS_HOST=new-redis-host
|
||||
# REDIS_PORT=6379
|
||||
# REDIS_PASSWORD=new-password
|
||||
|
||||
docker compose restart dlweb redis
|
||||
```
|
||||
|
||||
> 使用 Docker 内置 Redis（默认），`REDIS_HOST` 应设为 `redis`（Docker 服务名），不是 `localhost`。
|
||||
|
||||
---
|
||||
|
||||
## 场景五：单独开启 / 关闭特定服务
|
||||
|
||||
### 服务清单与依赖关系
|
||||
|
||||
| 服务名 | 容器名 | 说明 | 依赖 |
|
||||
|--------|--------|------|------|
|
||||
| `nginx` | `youle-nginx` | 反向代理 + SSL | api / dlweb / wxserver |
|
||||
| `api` | `youle-api` | 游戏核心 API | — |
|
||||
| `dlweb` | `youle-dlweb` | 代理管理后台 | redis |
|
||||
| `wxserver` | `youle-wxserver` | 微信小程序后端 | — |
|
||||
| `syncjob` | `youle-syncjob` | 每 30s 数据同步 | dlweb（内网） |
|
||||
| `cronjob` | `youle-cronjob` | 每日凌晨报表任务 | dlweb（内网） |
|
||||
| `redis` | `youle-redis` | 缓存 | — |
|
||||
| `certbot` | `youle-certbot` | 证书自动续签 | — |
|
||||
|
||||
### 开启单个服务
|
||||
|
||||
```bash
|
||||
docker compose up -d api
|
||||
docker compose up -d dlweb
|
||||
docker compose up -d wxserver
|
||||
docker compose up -d syncjob
|
||||
docker compose up -d cronjob
|
||||
```
|
||||
|
||||
### 关闭单个服务
|
||||
|
||||
```bash
|
||||
docker compose stop api
|
||||
docker compose stop syncjob
|
||||
|
||||
# stop + 删除容器（下次 up 会重新创建）
|
||||
docker compose rm -sf syncjob
|
||||
```
|
||||
|
||||
> `stop` 只停止容器，不删除；`rm -sf` 停止并删除容器（均不会丢失数据 volume）。
|
||||
|
||||
### 常见场景
|
||||
|
||||
**只重建并重启某个业务服务（代码更新后）：**
|
||||
```bash
|
||||
docker compose up -d --build api
|
||||
docker compose up -d --build dlweb
|
||||
docker compose up -d --build wxserver
|
||||
```
|
||||
|
||||
**关闭 certbot 自动续签（调试期间避免请求频率限制）：**
|
||||
```bash
|
||||
docker compose stop certbot
|
||||
docker compose up -d certbot # 恢复
|
||||
```
|
||||
|
||||
**仅重启 nginx（修改配置后生效）：**
|
||||
```bash
|
||||
docker compose restart nginx
|
||||
# 或热重载（不中断连接）
|
||||
docker exec youle-nginx nginx -s reload
|
||||
```
|
||||
|
||||
**查看所有服务当前状态：**
|
||||
```bash
|
||||
docker compose ps
|
||||
# 或
|
||||
./deploy.sh status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 操作速查表
|
||||
|
||||
| 变更内容 | 修改 `.env` 中的变量 | 重启命令 | 额外操作 |
|
||||
|---------|---------------------|---------|---------|
|
||||
| 更换域名 | `ROOT_DOMAIN`（子域名不标准时单独覆盖） | `./deploy.sh ssl-init && ./deploy.sh restart` | DNS 解析 + 微信后台 |
|
||||
| API 数据库 | `API_DB_*` | `docker compose restart api` | RDS 白名单 |
|
||||
| DLWEB 数据库 | `DLWEB_DB_*` | `docker compose restart dlweb` | RDS 白名单 |
|
||||
| 游戏数据库 | `EXT_GAME_DB_*` | `docker compose restart dlweb syncjob cronjob` | RDS 白名单 |
|
||||
| 战绩数据库 | `EXT_GRADE_DB_*` | `docker compose restart dlweb` | RDS 白名单 |
|
||||
| Redis | `REDIS_*` | `docker compose restart dlweb redis` | — |
|
||||
| 微信密钥 | `WX_*` | `docker compose restart api dlweb wxserver` | 微信后台 |
|
||||
| 整体迁移 | 视情况 | `./deploy.sh ssl-init && ./deploy.sh up` | DNS + RDS 白名单 |
|
||||
|
||||
---
|
||||
|
||||
## 数据持久化
|
||||
|
||||
以下 Docker Volume 用于持久化存储：
|
||||
|
||||
| Volume | 挂载点 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `api-logs` | /var/www/html/logs | API 服务日志 |
|
||||
| `api-source-logs` | /var/www/html/source/logs | API source 模块日志 |
|
||||
| `dlweb-logs` | /var/www/html/api/logs | DLWEB 服务日志 |
|
||||
| `dlweb-debug` | /var/www/html/api/ext/debug | DLWEB 同步/报表调试日志 |
|
||||
| `redis-data` | /data | Redis 持久化数据 |
|
||||
| `shared-signal` | /shared | syncjob ↔ cronjob 暂停信号文件 |
|
||||
| `certbot-webroot` | /var/www/certbot | ACME 域名验证文件 |
|
||||
| `certbot-certs` | /etc/letsencrypt | SSL 证书文件 |
|
||||
Reference in New Issue
Block a user