docs: 部署文档

- README：项目概览、快速开始、目录结构、重要提示
- 01 环境准备：硬件/系统/Docker 版本、镜像仓库、端口、防火墙、可选外部服务
- 02 配置说明：.env 必填与可选项、10 份应用配置逐项说明、启动前自检
- 03 启动与验证：首次初始化流程、状态检查、6 步验证清单、首次登录必做项
- 04 可选服务：挡板 onelink-mock、飞书 bot、自带 nginx（含 HTTPS）、组合启动
- 05 升级与备份：版本固定、升级回滚、备份脚本与恢复、日志清理、监控指标
- 06 故障排查：启动/功能/性能/网络四类共 20 个问题

docs/04-可选服务.md

@@ -0,0 +1,168 @@
+# 可选服务
+
+以下服务默认不启动，按需通过 profile 开启。
+
+## 一、运营商接口挡板（onelink-mock）
+
+### 用途
+
+模拟中国移动 OneLink 接口。**没有真实运营商环境时，靠它跑通完整链路**：
+
+```
+admin-svr → worker-svr → upstream-chan → onelink-mock
+```
+
+不开挡板时，`upstream-chan` 会尝试连接真实运营商接口，没有凭据则批次执行、状态同步、流量查询全部失败。
+
+### 启动
+
+```bash
+docker compose --profile with-mock up -d
+```
+
+验证：
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/api.json
+```
+
+预期 `200`。管理界面在 `http://127.0.0.1:8080/swagger`。
+
+### 配置
+
+挡板自身无需配置，数据存在容器内 SQLite（`./data/mock/onelink_mock.db`）。
+
+`upstream-chan` 的配置里已预置指向：
+
+```yaml
+dependencies:
+  sim_yd_mock_v5:
+    url: "http://onelink-mock:8080/v5/"
+```
+
+数据库种子脚本 `schema/08-seed-mock-channel.sql` 已插入一条 Mock 通道（`channel_yd_mock`）并指向该地址。
+
+`app-server` 若要使用挡板，把 `upstream.onelinkMock.enabled` 改为 `true` 并填写 `baseUrl: "http://onelink-mock:8080/v5"`。
+
+### 造测试卡
+
+挡板支持生成模拟卡片，用于验证查询、开停复机、续费等流程。具体接口见挡板 Swagger 页面。
+
+### 对接真实运营商
+
+1. 删除或注释 `upstream-chan` 配置里的 `sim_yd_mock_v5` 段
+2. 在平台「通道管理」中录入真实运营商通道（AppKey、AppSecret、接口地址）
+3. 停用 Mock 通道，避免卡片误挂到 Mock 上
+
+```bash
+docker compose --profile with-mock stop onelink-mock
+```
+
+## 二、飞书通知（bot）
+
+### 用途
+
+把全量同步完成、失败告警等运维事件推送到飞书群。
+
+### 准备
+
+在飞书开放平台创建自建应用，获取：
+
+| 项 | 获取方式 |
+| --- | --- |
+| `appId` / `appSecret` | 应用凭证页面 |
+| `chatId` | 目标群的会话 ID |
+
+填入 `.env`：
+
+```bash
+FEISHU_APP_ID=cli_xxxxxxxx
+FEISHU_APP_SECRET=xxxxxxxx
+FEISHU_CHAT_ID=oc_xxxxxxxx
+```
+
+### 启动
+
+```bash
+docker compose --profile with-bot up -d
+```
+
+bot 依赖 `worker-svr` 生成的全量同步归档（`./data/logs/worker-svr/full-sync`），需该目录已有数据才会产生通知。
+
+## 三、自带反向代理（nginx）
+
+### 用途
+
+把分散在各端口的服务统一到域名下按路径分流。宿主机已有 nginx 或面板时不需要。
+
+### 域名字段
+
+编辑 `config/nginx/iotlcm.conf`，把示例域名替换为实际域名：
+
+| 域名 | 分流到 |
+| --- | --- |
+| `api.your-domain.example.com` | openapi（`/openapi/v3/`、`/route/open/`） |
+| `admin.your-domain.example.com` | 管理端前端 + `/docs/` 文档站 |
+| `app.your-domain.example.com` | 小程序前端 + `/app/api/v1/` 后端 |
+
+### 启动
+
+```bash
+docker compose --profile with-nginx up -d
+```
+
+默认监听 80 端口，改 `.env` 的 `NGINX_HTTP_PORT` 可调整。
+
+### 使用宿主机 nginx
+
+不启动容器时，把 `config/nginx/iotlcm.conf` 中的 `upstream` 与 `location` 段落复制到宿主机 nginx 配置。
+
+需注意：
+
+- 宿主机 nginx 无法解析 compose 内的服务名，`upstream` 要改为 `127.0.0.1:<端口>`
+- 例如 `server admin-svr:8008;` → `server 127.0.0.1:8008;`
+
+### HTTPS
+
+自带 nginx 配置未包含证书。启用 HTTPS 需：
+
+1. 准备证书文件
+2. 在 `iotlcm.conf` 的 server 块加入：
+
+```nginx
+listen 443 ssl;
+ssl_certificate     /etc/nginx/certs/fullchain.pem;
+ssl_certificate_key /etc/nginx/certs/privkey.pem;
+ssl_protocols TLSv1.2 TLSv1.3;
+```
+
+3. 在 compose 的 nginx 服务增加证书目录挂载：
+
+```yaml
+volumes:
+  - ./data/certs:/etc/nginx/certs:ro
+```
+
+4. 增加 80 → 443 跳转：
+
+```nginx
+server {
+    listen 80;
+    server_name admin.your-domain.example.com;
+    return 301 https://$host$request_uri;
+}
+```
+
+## 四、组合启动
+
+多个 profile 可同时启用：
+
+```bash
+docker compose --profile with-mock --profile with-nginx up -d
+```
+
+查看当前启用的 profile 与对应的服务：
+
+```bash
+docker compose --profile with-mock config --services
+```