# 常见运维操作

---

## 场景一：更换域名

当需要将服务迁移到新域名时（例如 `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 证书文件 |