baiyue-firstleg/file

File Service 使用与运维说明

File Service 同时承载企业资质文件和公共导出下载中心。公共导出采用数据库任务表、事务 Outbox、RocketMQ 和业务 Provider；完整架构与接口契约见 ../docs/公共导出与下载中心接入说明.md。

公共导出运行条件

创建导出任务只会写入 file_export_task 和 file_export_outbox。以下三个组件全部启用后，任务才会从 PENDING 继续执行：

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 服务的部署阶段。

测试环境还必须配置：

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 清理的临时工作区：

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 用户，应修正挂载目录所有权。

部署后的正常状态：

rocketmq-namesrv     Up
rocketmq-broker      Up
rocketmq-topic-init  Exited (0)

rocketmq-topic-init 是一次性初始化容器，Exited (0) 表示 Topic、消费组和 DLQ 初始化成功。

验证 Broker 注册结果：

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 任务无需重建或手工改状态。

快速排查

任务状态查询：

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 查询：

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，否则会绕过租约、幂等和消息投递链路。

验收

测试环境主链路验收使用：

$env:ADMIN_ACCESS_TOKEN = '<测试环境平台用户Token>'
.\scripts\export-center-test-env-acceptance.ps1 `
  -GatewayBaseUrl 'http://8.163.30.128:9000'

脚本会创建真实 CUSTOMER_LIST 任务、轮询终态、下载文件并检查 XLSX ZIP 签名。Token 只通过当前进程环境变量注入，不写入仓库文件。