OpenJellyfish
用户指南 · 12

常见问题（FAQ）

Q: 注册时提示"注册码无效"？

A: 确认 config/registration_keys.json 文件存在且包含有效注册码。

  • 命令行：python generate_keys.py 生成新注册码
  • 桌面 App：进入「注册码管理」页生成
  • 每个注册码只能使用一次

Q: 前端无法连接后端？

A: 确认：

  1. 后端 FastAPI 已在 :8000 启动（访问 http://localhost:8000/docs 验证）
  2. 前端开发服务器 Vite 在 :3000 启动（自动代理 /api → :8000）
  3. 如使用 Docker，检查 docker compose logs -f 确认两个服务都已就绪
  4. 如使用桌面 App，进入「关于 / 工具」打开日志目录排查

Q: 模型列表为空？

A: 至少需要配置一个有效的 API Key：

  • ANTHROPIC_API_KEY：启用 Claude 系列模型
  • OPENAI_API_KEY：启用 GPT 系列模型 + 多媒体生成能力

或在 设置 → 通用 → API Keys 中配置自己的 Key（推荐）。

Q: 联网搜索不可用？

A: Admin Agent 默认启用联网工具，但需要配置搜索 API：

  • CLOUDSWAY_SEARCH_KEY（推荐，优先使用）
  • TAVILY_API_KEY（备选）

可在 设置 → 通用 → API Keys 中配置。

Q: 图片/语音/视频生成失败？

A: 确认已配置 OPENAI_API_KEY。如果需要使用不同的 API Key 或端点，可通过 IMAGE_API_KEY / TTS_API_KEY / VIDEO_API_KEY 分别覆盖（环境变量或 per-admin 设置均可）。

Q: 微信扫码后无法收到消息？

A: 参考以下检查清单：

  1. 确认 iLink Bot 服务端正常（扫码后应看到状态变为"已连接"）
  2. 检查后端日志中 wechat.* 相关日志（需要 LOG_LEVEL=INFO）
  3. iLink（国内）需要直连，不走代理
  4. 检查微信 session 是否过期（context_token 失效），重新扫码
  5. Admin 微信和 Service 微信是两套独立栈，不要混淆

Q: 微信中看到字面 <<FILE:...>> 字符串？

A: 应该已被 delivery.py::extract_media_tags 自动解析。如果仍出现：

  1. 检查文件路径是否真实存在
  2. 查看后端日志是否报媒体下载失败
  3. 确认是不是非 send_message 工具调用产生的文本（如 web_search 结果）

Q: 脚本执行失败 / "队列繁忙"？

A: 脚本在沙箱中执行，注意以下限制：

  • 不能导入危险模块（subprocess、pathlib、ctypes、io、pickle、threading 等）
  • 不能使用 exec、eval、getattr、setattr 等危险内置函数
  • 文件路径使用相对路径（../docs/file.csv，不是 /docs/file.csv），脚本的 cwd 是 scripts/ 目录
  • 内存限制 1024 MB，进程数限制 256
  • 全局并发 4 个脚本（可通过 SCRIPT_CONCURRENCY 调整）
  • 排队超时 180 秒（可通过 SCRIPT_QUEUE_TIMEOUT 调整）

Q: 定时任务不触发？

A:

  1. 检查任务的 next_run_at（详情 / 谱系图节点状态）
  2. 确认时区：设置 → 通用 → 时区；创建任务时会记录 tz_offset_hours
  3. cron 按你设置的时区解释；once 建议带时区后缀（如 2026-12-31T09:00:00+08:00）
  4. v2 使用堆驱动调度，到期约 1 秒内触发；侧栏只列 root，子任务在谱系图查看
  5. 若服务 OOM，可设 DISABLE_SCHEDULER=1 或调低 SCHEDULER_MAX_CONCURRENT（见开发指南）

Q: 对话排队 / 中断不生效？

A: 队列与 ↵ 立刻执行 仅 Admin 对话页；需当前会话正在流式输出且非 HITL 等待。中断会保留 partial 回复并同连接续跑。

Q: 工作区锁导致 Agent 无法写文件？

A: 查看 chat 顶栏锁面板：是否有其他进程（定时任务 / 另一对话）占用同路径。可手动释放锁（不中止 Agent）或等进程结束自动释放。

Q: 如何备份用户数据？

A: 推荐 设置 → 数据备份 按模块导出 ZIP（见 §6.5.6）。也可手动备份：

  • 本地：users/ + data/（含 checkpoints.db、encryption.key）
  • Docker：./data/users/ volume
  • S3：对象存储 + 本地 users/{uid}/ 配置目录
  • 重要：备份 ENCRYPTION_KEY 或 data/encryption.key，否则 API Key 无法解密

Q: 收件箱有消息但没有自动转发到我的微信？

A:

  1. 确认你已通过 设置 → 微信接入 接入了 Admin 微信
  2. 检查 users/{你的用户名}/admin_wechat_session.json 是否存在
  3. Inbox Agent 会智能评估是否值得转发，不是每条都会转
  4. 查看 inbox agent 的运行日志（在收件箱详情页可见）

Q: Tauri 桌面 App 在 Windows 启动报 Cannot load native module 'Crypto.Util._cpuid_c'？

A: 这是已修复的 Windows \\?\ 扩展长路径前缀 bug。请：

  1. 升级到最新版桌面 App
  2. 如果是自构建，确认 lib.rs 中包含 strip_win_extended_prefix() helper
  3. 详见 开发指南 §12.5.1

Q: per-admin API Key 设置后是否安全？

A:

  • AES-256-GCM 加密存储在 users/{uid}/api_keys.json
  • master key 在 data/encryption.key（或 ENCRYPTION_KEY 环境变量覆盖）
  • 前端只读取脱敏版本（如 sk-...abc123）
  • 通过 HTTPS 传输（生产环境务必启用 SSL）
  • 严格保护 master key 文件：丢失后所有 user API Key 都无法解密

Q: 我能让多个 Admin 共用一份 API Key 吗？

A: 不能。每个 Admin 独立配置 users/{uid}/api_keys.json。如果想统一管理，可以在环境变量中配置全局默认 key，让所有未单独配置的用户 fallback 使用。

Q: Service 数据如何隔离？

A: 严格隔离：

  • 每个 Service 在 users/{admin_id}/services/{service_id}/ 下
  • 每个 Consumer 对话在 users/{admin_id}/services/{svc_id}/conversations/{conv_id}/
  • Consumer 生成的文件在自己对话的 generated/ 目录
  • Consumer 看不到 Admin 的文件系统、其他 Service、其他 Consumer 的数据

Q: 主题切换后部分组件颜色不对？

A: 大部分组件已迁移到 --jf-* CSS 变量。如果发现遗漏，请到 frontend/src/styles/themes.css 检查变量定义，或将硬编码颜色改为 var(--jf-primary) 等。详见 开发指南 §5.9。

Q: 如何查看后台日志？

A:

  • 桌面 App：「关于 / 工具」→「日志目录」，按天滚动的 log 文件
  • 命令行：终端直接看 stdout，或 python launcher.py 启动的子进程也会写到 logs/{name}-YYYYMMDD.log
  • Docker：docker compose logs -f openjellyfish

Q: Docker 部署后端反复重启，日志报 sqlite3.OperationalError: unable to open database file？

A: 数据目录权限问题。容器以 jellyfish (uid=1000) 运行，但宿主机 ./data 目录的 owner 是 root，容器内进程没法写入 checkpoints.db。

解决（在项目根目录执行）：

bash
mkdir -p ./data/users
sudo chown -R 1000:1000 ./data
docker compose restart openjellyfish

验证：

bash
ls -ld ./data ./data/users
# 期望 owner 是 1000:1000

顺便说明：FastAPI lifespan 在多 router 场景下会嵌套 merged_lifespan，所以你看到的 traceback 会有一长串重复的 routing.py:216 帧，这是正常现象。真正的错误只看最底下两行（异常类型 + 消息）。

Q: Docker 部署后域名打不开，但服务器本地 curl http://localhost 能通？

A: 排查顺序：

  1. DNS：nslookup yourdomain.com 是否解析到你的服务器 IP；Cloudflare 控制台确认 A 记录是 Proxied（橙色云朵）。
  2. 防火墙 / 安全组：80 端口对外是否放行（云厂商控制台的安全组、ufw status）。
  3. Cloudflare SSL 模式：必须设为 Flexible（边缘 HTTPS、回源 HTTP）。如果错误地选了 Full / Full(Strict) 但服务器只有 80 端口，会出现无限 301 或 525 错误。
  4. nginx 是否真在 80：docker compose ps 看 openjellyfish-nginx 是否 Up，0.0.0.0:80->80/tcp。
  5. 流式输出"一坨一坨"出来：项目内置 nginx 已经为 /api/chat 关闭了 proxy_buffering；如果服务器前面还有一层反代（自建 nginx / Caddy / Traefik），那一层也要关 buffering 并支持 WebSocket Upgrade，否则 SSE 会被缓冲。
上一篇←环境变量配置