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：
- Reconciler：
true / false / false - Reconciler + Publisher：
true / true / false - 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 只通过当前进程环境变量注入，不写入仓库文件。