故障排查

本篇汇总部署与运行中常见问题的排查方法。遇到问题先看这里，大多数情况能快速定位。

容器启动失败

现象

容器反复重启或立即退出。

排查

docker logs linkoo --tail 100

常见原因：

• 数据库连不上：检查 AP_POSTGRES_HOST/PORT/PASSWORD，确认网络可达
• Redis 连不上：检查 AP_REDIS_HOST/PORT
• 密钥未设置：AP_JWT_SECRET、AP_ENCRYPTION_KEY 必填
• 端口占用：AP_PORT（默认 8080）被其他进程占用

Webhook 触发器不工作

现象

配置了 Webhook 触发器，但外部系统回调后流程不启动。

排查

• 检查 AP_FRONTEND_URL 是否为公网可达的 HTTPS 地址（Webhook URL 基于此生成）
• 用 curl 测试 Webhook URL 是否能返回响应
• 确认反向代理（Nginx/Caddy）正确转发到链盒端口
• 查看运行历史是否有对应的触发记录

流程执行超时

现象

流程运行状态一直卡住或最终报超时失败。

排查

• 检查是否触达 AP_FLOW_TIMEOUT_SECONDS（默认 600 秒）上限
• 定位是哪个步骤慢——在运行历史点开看每步耗时
• 外部系统响应慢？给该动作配置合理的超时与重试
• 循环处理大量数据？考虑分批或用 Worker 分离

连接器认证失败（401/403）

• OAuth2 连接：凭证过期，重新授权
• 静态凭证：检查 API Key/密码是否正确、权限是否充足
• 自建系统：确认接口地址（base_url）正确、网络可达

日志被截断

如果运行历史的输出显示不全，可能是日志长度限制。代码节点的输出建议控制大小， 大对象先用 toJson 转换或只取关键字段。

WebSocket 连接问题

实时运行状态依赖 WebSocket。如果状态不实时更新但流程实际在跑：

• 反向代理需正确转发 WebSocket 升级（Nginx 配置 proxy_http_version 1.1 + upgrade 头）
• CDN/负载均衡需支持 WebSocket（或长连接）

重置管理员密码

忘记管理员密码时，可通过命令行重置：

docker exec -it linkoo node dist/packages/server/cli.js user reset-password \
  --email admin@example.com \
  --new-password NewStrongPassword123

查看完整日志

# 实时跟踪日志
docker logs -f linkoo

# 只看最近 200 行
docker logs linkoo --tail 200

# 看特定时间段
docker logs linkoo --since 30m