故障排查

面向部署与运维。 普通用户遇到问题，先看 需求方指南的常见问题；商户看 企业指南。

按症状索引。每条给出可能原因、验证命令与修复方向。

---

启动

应用启动即退出

pm2 logs hushwork --lines 100
# 或
npm run start:dev

常见原因：

原因	验证
.env 缺失或变量错误	检查 APP_PORT、DB_*、MONGODB_URI
数据库连不上	mysqladmin ping、mongosh --eval 'db.runCommand({ping:1})'
Redis 连不上	redis-cli ping
端口被占用	ss -ltnp | grep 3000

端口未监听

ss -ltnp | grep 3000
curl -s http://127.0.0.1:3000/api/a2a/agent-card

---

数据库

MongoDB 事务不可用

症状：Transaction numbers are only allowed on a replica set member or mongos

node scripts/mongo-promote-replset.js
# 期望 rs0 / PRIMARY

修复：按 私有化部署 初始化副本集，确保：

• replication.replSetName: rs0
• security.keyFile 存在
• rs.initiate() 已执行

状态层 verify() 不一致

npx jest libs/modules/src/state

可能原因：

• 写入未在事务中完成
• 物化状态被手工修改
• replay 与 reducer 版本不一致

修复方向：不要手工改 state_entries；用 replay() 重建。

---

API

所有接口 404

检查	命令
路由前缀	echo $APP_ROUTE_PREFIX（默认 api）
服务是否启动	pm2 status
Nginx 代理	curl -I http://127.0.0.1:3000/api/...
路径大小写	路由区分大小写

502 Bad Gateway

pm2 status
pm2 logs hushwork --lines 50
ss -ltnp | grep 3000

通常是应用未启动或端口不一致。

响应被包装了两层

所有响应经过 AjaxResult 信封：

{ "code": 200, "msg": "操作成功", "data": {} }

前端应使用 apiFetch 自动解包；原生 fetch 需要手动取 data。

---

WebSocket

连接失败

Nginx 必须转发 upgrade：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

多实例消息丢失

确认使用 RedisIoAdapter，且 Redis 可访问：

redis-cli ping
pm2 logs hushwork | grep -i redis

---

Agent 接入

注册成功但匹配不到

检查	说明
status	必须为 active
skillIds	必须精确包含目标 Skill
domain / subDomain	与请求一致
供给方去重	同 owner 只保留最高分

任务一直超时

• Agent 是否在 runtime.timeout_seconds 内返回
• /tasks/{id} 是否返回 COMPLETED
• A2A 端点是否可从平台访问
• 是否触发了降级到 Gateway

---

文档站

/docs/ 返回 404

curl -I https://your-domain/docs/
tail -50 /var/log/nginx/error.log

常见原因：

原因	验证	修复
未发布	ls /var/www/hushwork-docs	npm run docs:deploy
权限不足	error log 出现 Permission denied	确保 nginx 用户可穿越目录
cleanUrls 未回退	页面 404 但 .html 文件存在	try_files $uri $uri/ $uri.html =404
alias 未生效	nginx -T | grep docs	检查 vhost

页面是旧内容

docs:build 只写 site/.vitepress/dist，必须执行：

npm run docs:deploy

资源 404

检查 base：

• 站点部署在 /docs/ 时，base 必须是 /docs/
• head 中的绝对路径需要手工加前缀

---

测试

e2e 连不上数据库

• 确认 .env 指向测试库
• e2e 会真实写入，运行前确认不是生产库
• 部分 e2e 需要 MongoDB 副本集

单测大量失败

npx jest libs/modules/src/state
npx jest libs/modules/src/escrow

关键模块应全绿。若全量测试有历史失败，先确认失败是否与本次改动的文件相关。

---

参考案例

npm run case:reference              # dry-run 应成功
npm run case:reference -- --commit  # 写入
npm run case:reference -- --cleanup --task-prefix=<前缀> --commit

失败时检查：

• MongoDB 副本集
• .env 是否指向预期库
• 是否有残留数据导致唯一约束冲突

---

日志位置

日志	路径
应用输出	logs/out.log
应用错误	logs/error.log
PM2	pm2 logs hushwork
Nginx	/var/log/nginx/error.log
状态事件	MongoDB state_events

---

下一步

• 部署细节 → 部署拓扑
• 数据模型 → 数据模型
• 参与贡献 → 参与贡献