FluxDown CLI / API 连接不上 — 17800 端口检查

常见症状

• fluxdown list 或 curl http://127.0.0.1:17800/api/v1/tasks 返回 Connection Refused。
• 返回 401 Unauthorized（认证失败）。
• 远程机器（比如 NAS 上）API 连不上。

排查步骤

1. 先确认 FluxDown Agent 层在跑

CLI/API 都连 Agent 层（fluxdown-agent）。Agent 没启动 → 端口根本不会监听。

• 桌面端 — FluxDown 桌面端启动时自动拉起 Agent。关掉桌面端（托盘图标）→ Agent 还在跑；托盘彻底退出 → Agent 和 Daemon 都停。
• Docker Server — 容器必须在运行：docker ps 检查 fluxdown-server 容器状态。
• NAS — DSM Package Center 或 Container Station 里看服务状态。

2. 检查端口绑定

桌面端默认绑定 127.0.0.1:17800（只允许本机访问，安全）。要允许 LAN 访问需要手动开启：

桌面端：设置 → 本地服务器 → 启用 LAN 访问（开启后绑定 0.0.0.0:17800，接受所有网卡连接）。

Docker Server 默认绑定 0.0.0.0:17800，因为需要从外部 Web UI 访问。

快速检查端口（PowerShell）：

netstat -ano | findstr 17800
# 应该看到一条 TCP LISTENING 记录

如果没看到 → Agent 没在跑或端口变了。

3. 检查认证 Token

API 所有写操作和大部分读操作需要 Bearer Token。Token 从：

• 桌面端 Windows — %APPDATA%\FluxDown\access_key.txt
• Docker Server — docker exec fluxdown-server cat /data/access_key.txt
• 桌面端设置页 — 设置 → API → 查看或重置 Access Key

错误 Token 会返回 401 Unauthorized，注意 Bearer 格式：

Authorization: Bearer <access_key>

4. 远程访问 NAS / Server 时的网络问题

从另一台机器（比如笔记本）连 NAS 上的 FluxDown Server：

# 测试连通性
curl http://<NAS-IP>:17800/api/v1/tasks -H "Authorization: Bearer <token>"

连不上时检查：

• 云安全组 — NAS 如果是云主机，云安全组/防火墙放行 17800 TCP。
• 路由器端口转发 — 局域网访问不需要；外网访问需要路由器做 NAT。
• Agent 的 Host 验证 — Agent 默认会验证 Host header 是不是 localhost，LAN 访问时接受所有 Host，但公网访问建议用 HTTPS 反向代理（见 Docker Headless Server 的安全暴露章节）。
• CORS — Agent 默认只允许 localhost Origin 跨域。LAN 上从浏览器调 API 需要开 LAN 访问后也放开 CORS。

5. CLI 连本地 vs 远程

# 连接本机正在跑的 FluxDown（默认 127.0.0.1:17800）
fluxdown list

# 连接 NAS 上的 FluxDown Server
fluxdown --server http://192.168.1.100:17800 list

# --local 直接在当前进程里嵌入引擎（不依赖任何正在跑的 FluxDown）
fluxdown add https://example.com/file.zip --local

6. aria2 兼容层连不上

aria2 JSON-RPC 的认证是 params[0] = "token:<access_key>" 格式，不是 Bearer header：

{"jsonrpc": "2.0", "id": "1", "method": "aria2.tellStatus", "params": ["token:<access_key>", ["<gid>"]]}

格式错了返回 401。URL 是 /jsonrpc 不是 /api/v1/*。

快速诊断表