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