Skip to main content

常见问题

本页汇总自部署运维与日常使用中最高频的问题。每个答案末尾附有对应手册页链接,深入细节请前往相应页面。

安装与首次运行​

首次登录的管理员账号是哪来的?​

Aivory 不通过环境变量预置管理员凭据。全新部署(用户数为 0)时,访问站点会自动进入首启设置页 /setup:填写邮箱、名字和密码(至少 8 个字符),该账号立即成为管理员并自动登录,无需邮箱验证。

一旦实例中存在任何账号,/setup 就永久失效(再访问返回 409)。所以如果你打开 /setup 看到报错,说明该实例已经初始化过,请走正常登录流程。

详见首次运行。

模型为什么不出现在选择器里?​

按以下顺序排查:

  1. 渠道未配置:先到管理后台「渠道」添加上游(类型:Anthropic / OpenAI / Gemini / OpenAI 兼容,填 Base URL + API Key)。
  2. 模型未创建或未启用:再到「模型」页面创建模型(选渠道、填上游模型 ID),并确认已启用。只有启用的模型才会出现在所有用户的选择器里。
  3. 标签筛选:模型选择器顶部有标签筛选芯片,确认当前没有选中一个把目标模型过滤掉的标签,切回「全部」即可。

如果只是想先体验界面,可以在 Compose 中设置 ENABLE_MOCK_PROVIDER=true 启用内置演示模型(默认 false)。

详见渠道与模型。

JWT_SECRET 一定要设吗?为什么重启后所有人都要重新登录?​

分两种情况:

  • 开发环境:JWT_SECRET 未设置时自动生成随机临时密钥。副作用是每次重启进程,全部会话失效,所有人需要重新登录。如果你在开发环境也想会话跨重启存活,设一个固定值即可。
  • 部署环境(AIVORY_ENV 非 dev,或 DATABASE_URL 指向 Postgres):必须设置至少 32 个字符的 JWT_SECRET,否则服务直接拒绝启动。

令牌有效期由 ACCESS_TTL(默认 30m)和 REFRESH_TTL(默认 720h,即 30 天)控制,Go duration 格式。

详见核心配置。

功能使用​

为什么知识库检索结果为空?​

最常见的两个原因:

  1. 未配置向量后端:QDRANT_URL 默认为空,为空时向量检索被禁用,RAG 走全文注入回退。小文档仍然可用,但真正的向量检索需要配置 Qdrant(生产 Compose 已内置)。
  2. 未配置嵌入模型:知识库文档入库需要嵌入模型。通过 EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL(默认 text-embedding-3-small)配置,或在管理后台设置嵌入模型。

另外确认文档状态已到 ready(状态流:pending → parsing → embedding → ready),卡在中间状态的文档不参与检索。

详见知识库与核心配置。

EMBEDDING_DIM 与嵌入模型不匹配怎么办?​

EMBEDDING_DIM 默认 1536(对应 text-embedding-3-small)。Qdrant collection 按维度命名为 aivory_c<维度>,如果你换用了输出维度不同的嵌入模型,必须把 EMBEDDING_DIM 改成新模型的真实维度,否则向量写入与检索会落在错误的 collection 上。

修改维度后,到管理后台「备份与迁移」的向量维护里重建向量:系统会从数据库存储的分块文本重新调用嵌入模型写入新 collection,不需要原始文件,但会消耗嵌入 API 调用。

详见备份与迁移。

扫描版 PDF 上传后解析不出内容?​

带文字层的 PDF 在本地毫秒级解析,不依赖任何外部服务;但扫描件 PDF(以及 DOCX / PPTX / XLSX / 图片)需要走 MinerU 云端 OCR。请确认已配置:

变量默认值说明
MINERU_API_URL空(Compose 里默认 https://mineru.net)MinerU API 地址
MINERU_API_KEY空MinerU 的 API 密钥,未配置则扫描件无法解析

详见知识库。

沙箱里的代码能联网吗?​

默认不能。沙箱网络由 Compose 变量 SANDBOX_NETWORK 控制,默认值为 none(完全无网络),这是刻意的安全默认值。只有当沙箱内代码确实需要访问互联网时,才把它改为 bridge。

不开网络也能覆盖大部分场景:模型会在沙箱外用 web_fetch / fetch_image 工具抓取网页和图片,抓到的内容自动暂存进沙箱的 /workspace/uploads/,Python 代码直接读文件即可。

未配置沙箱时

SANDBOX_BASE_URL 为空时,python_execute 进入安全模式,只执行简单算术。生产 Compose 已内置沙箱容器(SANDBOX_BASE_URL=http://sandbox:8000)。

详见沙箱部署与 Python 沙箱使用。

上传大小限制在哪里改?​

分三层:

  1. 服务端硬上限:MAX_UPLOAD_BYTES,默认 52428800(50 MB),任何上传都不能超过它。
  2. 管理后台细化限制:管理员可以在后台按图片和文件分别收紧限制(只能比硬上限更小)。
  3. 反向代理:如果走 Nginx 等反代,还需要调大代理层的请求体上限(如 client_max_body_size),否则请求在到达 Aivory 之前就被反代拒绝。

备份导入是另一个独立的上限:MAX_BACKUP_BYTES,默认 20 GiB。

详见核心配置、站点设置与反向代理。

每个用户每天能发多少条消息、生成多少张图?​

环境变量层面的全局默认值:

变量默认值说明
DAILY_MESSAGE_LIMIT200每用户每日消息条数
IMAGE_DAILY_LIMIT30每用户每日图片生成张数

在此之上,管理员还可以通过用户组、积分与按模型配额做更精细的控制(定时额度、永久积分、发送前费用预检、兑换码)。详见用户与配额。

部署与网络​

用 HTTP 明文部署可以吗?​

可以正常工作。Aivory 前端对浏览器加密能力做了特性检测:在非安全上下文(HTTP 明文)下,请求签名等功能自动回退到纯 JS 实现,不依赖只有 HTTPS 才提供的 crypto.subtle 等 API。

仍然建议上 HTTPS

明文传输意味着密码、令牌与对话内容在网络上可被窃听;此外浏览器的部分能力(如 PWA 安装)只在安全上下文下可用。生产环境建议用反向代理或 Cloudflare 终结 TLS。

详见反向代理与 Cloudflare 接入。

如何更换域名?​

单容器同源部署下,Aivory 对域名自适应:前端与 /api 同源,解析到哪个域名哪个域名就能用,不需要改 ALLOWED_ORIGINS 或任何 origin 配置。更换域名只需:

  1. 把新域名的 DNS 解析指到服务器,更新反向代理的 server_name 与证书。
  2. 如果配置了 OAuth 登录:多域名或换域名场景需设置 OAUTH_CALLBACK_BASE_URL 固定回调的 scheme://host,并同步更新 OAuth 提供商侧的回调地址;跨域登录还需把允许跳回的 origin 加入 OAUTH_RETURN_ORIGINS 白名单。
  3. 只有前后端分离部署才需要维护 ALLOWED_ORIGINS(逗号分隔),并注意前端的 VITE_API_BASE 是构建期变量,改动需重新构建。

详见核心配置与反向代理。

该选 SQLite 还是 Postgres?​

DATABASE_URL 默认指向嵌入式 SQLite(./data/aivory.db,WAL 模式),零依赖即可启动,适合个人使用与小规模试用;postgres:// 前缀则切换到 PostgreSQL,生产 Compose 默认使用 Postgres 16。

注意:DATABASE_URL 指向 Postgres 会被视为「部署环境」,触发部署级安全校验(例如强制要求 JWT_SECRET 至少 32 字符)。

选型不必焦虑:得益于引擎中立的备份格式,SQLite 起步后随时可以把全量备份导入 Postgres 部署,不丢任何数据。详见 SQLite 模式。

数据与升级​

忘记管理员密码怎么办?​

按可用性从高到低:

  1. 找回密码流程:登录页走「忘记密码」,通过发送到邮箱的 6 位验证码重置(验证码连错 5 次会作废,需重新发起)。
  2. 另一位管理员协助:如果实例中还有其他管理员账号,可由对方在管理后台的用户管理中修改你的密码。
  3. 从备份恢复:如果以上都不可行且你有完整备份,导入备份后可以用备份中的账号密码登录。

注意 /setup 在已有账号的实例上永久失效,不能靠它重建管理员。详见账号管理与用户与配额。

备份能跨数据库引擎恢复吗?​

能,这是 Aivory 备份格式的核心设计。完整备份是单个 zip:manifest + 每表一个 JSONL(引擎中立)+ 可选的文件目录 + 可选的 Qdrant 向量点位。SQLite 备份可以导入 Postgres 部署,反之亦然,序列与外键自动处理。

导入时需注意:

  • 导入是整库替换,需要输入确认词 REPLACE;完成后当前所有会话失效,用备份里的账号密码重新登录。
  • 安全机制:除「执行导入的管理员邮箱」外,备份带来的其它 admin 一律降级为普通用户(防恶意备份提权)。因此新实例首启管理员的邮箱应与旧实例管理员一致。
  • 导入大小上限为 MAX_BACKUP_BYTES(默认 20 GiB)。
  • 若备份未含向量,可在「向量维护」里从数据库分块文本重建,无需原始文件。

详见备份与迁移。

如何升级到新版本?​

标准流程:

cd Aivory/deploy
# 建议先在管理后台导出一份完整备份
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

数据库结构在新版本启动时自动迁移,无需手工执行 SQL。镜像 tag 由 .env 中的 IMAGE_TAG 控制(默认 latest;也可以钉住具体版本号)。

升级前备份

虽然迁移是自动的,仍建议每次升级前在管理后台「备份与迁移」导出一份完整备份,万一需要回退可以整库恢复。

详见 Docker Compose 部署与备份与迁移。