JellyfishBot
用户指南 · 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 字段（在运行记录页面可见）
  2. 确认时区设置正确：通用 → 时区
  3. cron 表达式按你设置的时区解释
  4. once 类型必须带时区后缀（如 2026-12-31T09:00:00+08:00）
  5. 调度器每 30s 检查一次，所以最近一次执行可能延迟数秒

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

A:

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

Q: 如何备份用户数据？

A:

  • 本地模式：备份 users/ 和 data/ 目录（含 checkpoints.db、encryption.key）
  • Docker 模式：备份 ./data/users/ 目录
  • S3 模式：S3 存储自带冗余，但 JSON 配置仍在本地，需同时备份本地 users/{uid}/（除 filesystem/ 外）和 data/
  • 重要：如果设置了 ENCRYPTION_KEY，记下这个值；否则备份 data/encryption.key 文件（master key），缺失会导致 API Key 无法解密

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 jellyfishbot
上一篇←环境变量配置