126 lines
5.0 KiB
Markdown
126 lines
5.0 KiB
Markdown
# File Service 使用与运维说明
|
||
|
||
File Service 同时承载企业资质文件和公共导出下载中心。公共导出采用数据库任务表、事务 Outbox、RocketMQ 和业务 Provider；完整架构与接口契约见 [`../docs/公共导出与下载中心接入说明.md`](../docs/公共导出与下载中心接入说明.md)。
|
||
|
||
## 公共导出运行条件
|
||
|
||
创建导出任务只会写入 `file_export_task` 和 `file_export_outbox`。以下三个组件全部启用后，任务才会从 `PENDING` 继续执行：
|
||
|
||
```dotenv
|
||
FILE_EXPORT_RECONCILER_ENABLED=true
|
||
FILE_EXPORT_PUBLISHER_ENABLED=true
|
||
FILE_EXPORT_CONSUMER_ENABLED=true
|
||
FILE_EXPORT_CONSUMER_CONCURRENCY=4
|
||
```
|
||
|
||
三个开关默认均为 `false`，避免 RocketMQ 尚未就绪时 File Service 启动失败。Docker 容器只在创建时读取环境变量；修改 Jenkins 环境文件后必须重新部署 File Service，`docker restart` 不会更新配置。
|
||
|
||
当前测试环境由 Jenkins 文件凭据 `firstleg-test-env` 注入这些变量；凭据内容变更后重新执行 `file` 服务的部署阶段。
|
||
|
||
测试环境还必须配置：
|
||
|
||
```dotenv
|
||
INFRA_NETWORK=firstleg-test-infra-network
|
||
ROCKETMQ_NAME_SERVER=rocketmq-namesrv:9876
|
||
ROCKETMQ_BROKER_IP=rocketmq-broker
|
||
MQ_TOPIC_PREFIX=test-
|
||
ROCKETMQ_DATA_DIR=/data/firstleg/rocketmq/store
|
||
```
|
||
|
||
File 与 RocketMQ 不暴露 MQ 宿主机端口，二者通过 `infra-network` 和 Docker 服务名通信。`ROCKETMQ_BROKER_IP` 不得填写 `localhost`、`127.0.0.1` 或宿主机公网地址。
|
||
|
||
## 测试环境首次部署 RocketMQ
|
||
|
||
在服务器的稳定仓库目录执行，不要依赖会被 Jenkins 清理的临时工作区：
|
||
|
||
```bash
|
||
cd /www/deploy/baiyue-firstleg
|
||
mkdir -p /data/firstleg/rocketmq/store
|
||
chown -R 3000:3000 /data/firstleg/rocketmq/store
|
||
|
||
DEPLOY_ENV=test \
|
||
INFRA_NETWORK=firstleg-test-infra-network \
|
||
ROCKETMQ_BROKER_IP=rocketmq-broker \
|
||
ROCKETMQ_DATA_DIR=/data/firstleg/rocketmq/store \
|
||
MQ_TOPIC_PREFIX=test- \
|
||
docker compose -f deploy/docker-compose.rocketmq.yml up -d
|
||
```
|
||
|
||
官方 `apache/rocketmq:5.3.1` 镜像使用 UID/GID `3000` 的 `rocketmq` 用户。宿主机存储目录若属于 `root:root` 且不可写，Broker 会反复重启；不要把 Broker 改成 root 用户，应修正挂载目录所有权。
|
||
|
||
部署后的正常状态：
|
||
|
||
```text
|
||
rocketmq-namesrv Up
|
||
rocketmq-broker Up
|
||
rocketmq-topic-init Exited (0)
|
||
```
|
||
|
||
`rocketmq-topic-init` 是一次性初始化容器，`Exited (0)` 表示 Topic、消费组和 DLQ 初始化成功。
|
||
|
||
验证 Broker 注册结果：
|
||
|
||
```bash
|
||
docker run --rm \
|
||
--network firstleg-test-infra-network \
|
||
apache/rocketmq:5.3.1 \
|
||
sh mqadmin clusterList -n rocketmq-namesrv:9876
|
||
```
|
||
|
||
输出必须包含 `BaiyueCluster`、`baiyue-file-export-broker` 和可访问地址 `rocketmq-broker:10911`。
|
||
|
||
## 分阶段启用导出
|
||
|
||
首次上线按以下顺序逐步修改环境文件，每一步都重新部署 File Service 并确认容器 `healthy`、`restartCount=0`：
|
||
|
||
1. Reconciler：`true / false / false`
|
||
2. Reconciler + Publisher：`true / true / false`
|
||
3. Reconciler + Publisher + Consumer：`true / true / true`
|
||
|
||
顺序均为 `RECONCILER / PUBLISHER / CONSUMER`。第二阶段应观察到 Outbox 从 `PENDING` 变为 `SENT`；第三阶段任务应从 `PENDING` 进入 `RUNNING`，最终进入 `SUCCEEDED` 或带明确原因的 `FAILED`。已有的 `PENDING` 任务无需重建或手工改状态。
|
||
|
||
## 快速排查
|
||
|
||
任务状态查询：
|
||
|
||
```sql
|
||
SELECT id, task_no, status, dispatch_version, attempt_count,
|
||
processed_rows, next_retry_at, lease_owner, lease_until,
|
||
requested_at, started_at, completed_at, failure_message
|
||
FROM file_export_task
|
||
WHERE id = ?;
|
||
```
|
||
|
||
Outbox 查询：
|
||
|
||
```sql
|
||
SELECT id, task_id, dispatch_version, topic, status, attempt_count,
|
||
next_retry_at, lease_owner, lease_until, sent_at, last_error
|
||
FROM file_export_outbox
|
||
WHERE task_id = ?
|
||
ORDER BY id;
|
||
```
|
||
|
||
| 现象 | 判断与处理 |
|
||
|---|---|
|
||
| Task `PENDING`、`attempt_count=0`，Outbox `PENDING`、`attempt_count=0` | Publisher 未启用或未运行 |
|
||
| Outbox `PENDING` 且有 `last_error` | Publisher 已尝试，检查 NameServer、Broker、Topic 和网络 |
|
||
| Outbox `CLAIMED` 且租约过期 | Publisher 中断，确认 Reconciler 已启用 |
|
||
| Outbox `SENT`，Task 仍为 `PENDING` | Consumer 未启用、未连接或存在消费积压 |
|
||
| File 启动时报 `connect to null failed` | NameServer/Broker 未运行，或未连接同一 `infra-network` |
|
||
| Broker 反复重启，数据目录为 `root:root` | 将挂载目录递归调整为 `3000:3000`，不要使用 root 运行 Broker |
|
||
|
||
不要手工把 Task 改为 `RUNNING` 或把 Outbox 改为 `SENT`，否则会绕过租约、幂等和消息投递链路。
|
||
|
||
## 验收
|
||
|
||
测试环境主链路验收使用：
|
||
|
||
```powershell
|
||
$env:ADMIN_ACCESS_TOKEN = '<测试环境平台用户Token>'
|
||
.\scripts\export-center-test-env-acceptance.ps1 `
|
||
-GatewayBaseUrl 'http://8.163.30.128:9000'
|
||
```
|
||
|
||
脚本会创建真实 `CUSTOMER_LIST` 任务、轮询终态、下载文件并检查 XLSX ZIP 签名。Token 只通过当前进程环境变量注入，不写入仓库文件。
|