跳到主要内容

管理员首次配置

适用版本

本文档基于 Aivory v2.4.7 编写。界面以简体中文为准，英文界面参见对应页面。

本页覆盖从“刚启动的空实例”到“普通用户可以聊天”的完整管理流程。个人版和完整版共享同一套管理后台与配置模型：区别只在默认依赖（个人版为内嵌 SQLite 向量、无本地沙盒；完整版默认带 PostgreSQL、Redis、Qdrant 和内部沙盒 sidecar），不是两套不同的后台功能。

前置条件​

  • 已通过 个人版部署 或 完整版部署 启动实例，浏览器能打开登录页。
  • 部署级环境变量（JWT_SECRET、DATABASE_URL 等）已按 环境变量 配置。
  • 至少一个模型服务商账号（OpenAI、Anthropic、Google 或任意 OpenAI 兼容网关）及其 API Key。

初始管理员是如何产生的​

理解引导机制有助于排障和写自动化脚本：

  1. 全新实例的数据库不预置任何用户，也没有任何环境变量可以“种出”管理员——不存在 ADMIN_PASSWORD 之类的启动参数。
  2. 前端启动时探测 GET /api/public/needs-setup，只要用户数为 0 就返回 {needs_setup: true}，应用会自动跳转到 /setup 初始化页面。
  3. 在 /setup 页面填写姓名、邮箱和密码后，前端调用 POST /api/setup（公开接口，按 IP 限速）。创建成功后该账户立即成为管理员并自动登录，不需要邮箱验证。
  4. 一旦系统中存在至少一个用户，/setup 通道永久关闭（重复提交返回 409 冲突），不能用它追加管理员。后续管理员需在“用户与访问 → 用户”中把已有账号提升为管理员。
  5. 后台所有管理页面位于 /admin 路径下，只有角色为管理员的账号可以进入。

追加管理员​

初始化完成后，第二个及以后的管理员只能由已有管理员操作：进入“用户与访问 → 用户”，搜索目标账号，将其角色改为管理员。建议至少保留两个独立管理员账号（不同登录方式更佳），避免单人不可用时锁死后台。

本地快建方式（可选）​

不走 Docker 也可以直接跑单机联调实例：

npm run build                                   # 构建前端到 dist/
cd server && go build -o aivory ./cmd/api
STATIC_DIR=../dist ./aivory                     # 打开 http://localhost:8787

第一个在 /setup 注册的账号同样自动成为管理员。注意：开发模式下若未设置 JWT_SECRET，进程会随机生成临时密钥，每次重启所有会话失效——这不是故障。

首次登录后先看“管理概览”

进入 /admin 后默认落在“总览 → 管理概览”页。顶部的配置健康状态会列出当前阻塞用户使用的警告（例如没有可用渠道、没有默认模型）；页面内还提供可跳过的配置引导漫游，随时可点“重新查看配置引导”再次打开。

管理概览页：配置健康状态与今日统计

管理概览：先处理“配置健康状态”中的警告，再考虑推荐配置。截图中模型名称为占位示例。

关于截图

本手册的管理页截图来自本地测试实例，模型渠道使用占位名称与假密钥，仅用于展示界面布局，不是真实可用的模型 ID 或端点。

能用：三步最小配置​

完成以下三步，普通用户就可以开始真实聊天。不要把任务模型、搜索、embedding、邮件或 Python 沙盒误当成首次聊天的硬性前置条件。

没有真实密钥也能先演练三步

个人版 compose 支持 ENABLE_MOCK_PROVIDER=true：会种入一条 Mock 渠道，不发出真实网络请求、返回可控假响应，用来零成本验证“渠道 → 模型 → 默认模型 → 流式回复”的完整链路。演练完成后关闭该变量并重启，换回真实渠道。

顺序后台位置完成标准常见错误
1AI 与模型 → 渠道至少一个渠道已启用，Base URL、类型和 API Key 可用Base URL 与服务商格式不匹配，或 Key 无权限
2AI 与模型 → 模型至少一个关联该渠道、已启用的聊天模型，request_id 非空只添加了 embedding/图片模型，或所属渠道被禁用
3AI 与模型 → 模型策略“默认对话模型”选中一个仍可用的聊天模型选中已删除、禁用或渠道失效的模型

逐步操作如下。

第 1 步：创建可用渠道​

  1. 进入“AI 与模型 → 渠道”，点击“新建渠道”。
  2. 填写：
    • 名称：仅用于管理员识别，建议标记环境、区域或账号，例如 OpenAI 生产。
    • 类型：与服务商协议匹配（OpenAI / Claude / Gemini 等）。“类型”决定签名与请求协议，模型名相同不代表接口兼容。
    • 接口格式：仅对话模型使用（如 OpenAI 的 chat 与 responses 两套协议），不确定时保持默认。
    • Base URL：留空使用厂商默认端点；走网关时填写上游 API 根地址（OpenAI 类型可使用 /v1 等路径）。
    • API Key：服务端密钥，明文保存在数据库中，只有管理员后台可见。
  3. 保存并启用。可在同一个新建对话框中点“从上游获取”直接勾选模型，稍后创建模型记录。

字段级细节、各类型差异与连通性测试见渠道、模型与策略。

第 2 步：添加聊天模型​

渠道不会自动让模型出现在用户选择器里，还需要模型记录：

  1. 进入“AI 与模型 → 模型”，点击“拉取新模型”，选择渠道后读取其上游模型列表，勾选需要的模型批量加入；无法列举模型的服务商可“新建模型”手动填写。
  2. 确认每条记录：类型为聊天、渠道关联正确、request_id (实际请求 ID) 与服务商文档完全一致、**启用（对用户可见）**已打开。
  3. 第一次建议只启用少量已验证模型。默认策略、配额和标签都可以之后再补。

第 3 步：设置默认模型并实测​

  1. 进入“AI 与模型 → 模型策略”，在“默认对话模型”中选择刚启用的聊天模型。
  2. 回到前台新建一条短对话，验证真实上游响应：能看到流式输出即通过。
  3. 若返回渠道错误、额度错误或模型不存在，先修复第 1、2 步，再继续任何增强配置。

用户视角的欢迎页：已启用的模型出现在输入框选择器中

三步完成后，普通用户在欢迎页即可看到并选择已启用的聊天模型。

模型策略页的“不可用”保护

若默认模型所属渠道被禁用或模型被删除，模型策略页会显示“部分已保存的模型策略当前不可用”的警告。每次修改策略后都重发一条测试对话，不要只相信下拉框里还能选中。

更好用：按场景逐项启用​

三步跑通后，按下面的顺序扩展，而不是在首日一次性打开所有开关：

能力先配置什么何时需要个人版与完整版差异
知识库与 RAGembedding 模型、正确维度、文档解析策略需要基于私有文档回答个人版用 SQLite 内嵌向量，完整版用 Qdrant
网页搜索搜索后端与 API Key / 自部署地址需要实时互联网信息配置方式相同
Python 与文件执行可访问的沙盒、资源限制、模型工具授权需要计算、图表、文件生成个人版默认无沙盒（可选 profile）；完整版默认内置
MCP、技能、提示词从低风险单个服务开始，测试并同步需要连接外部业务系统配置方式相同
语音输入STT 渠道与密钥需要麦克风转写配置方式相同
邮件SMTP、发件地址和 TLS邮箱验证、重置密码、运营通知完整版长期多人部署应优先配置
OAuth 与注册策略先完成 HTTPS 域名，再单个身份源验证需要第三方登录或组织入口配置方式相同，见用户、登录与工作区
工作区、套餐和支付权限、配额、积分与支付回调面向团队或商业用户见套餐、积分与支付

配置优先级与变更管理​

后台设置与环境变量承担不同职责，不能混写：

  • 后台保存的配置写入数据库 settings 键值表，按请求热生效，无需重启：渠道 Key、模型、注册策略、SMTP、对象存储、搜索、沙盒地址与密钥、积分换算等绝大多数日常配置。
  • 环境变量主要承担启动默认值与部署拓扑：DATABASE_URL、REDIS_URL、QDRANT_URL、VECTOR_BACKEND、JWT_SECRET、ALLOWED_ORIGINS、MAX_UPLOAD_BYTES 等；修改后需要重启 aivory-api。
  • 官方 Compose 文件对数据库、Redis、Qdrant 和内置沙盒连接有明确的高优先级值，在 .env 里写同名变量未必覆盖它，先读部署文件再改环境。
  • “备份与迁移 → 导出配置”生成的 ZIP 包含渠道、OAuth、SMTP、支付与存储凭据明文，必须按密码库级别的机密保存。

建议在接入真实用户之前建立一份“变更后验收”清单：管理员与普通用户登录、默认模型对话、上传小文件、知识库检索、一个受限工具调用、备份导出，以及需要时的 OAuth 回调和支付沙箱测试。完整的升级与备份流程见升级、备份与恢复。

上线第一周节奏​

时间动作
D0完成三步最小配置 + 首日验收清单；备份导出演练一次
D1打开“用量与计费”看 D0 真实成本与错误率；必要时下调模型价格或换默认模型
D2–D3启用第一个增强能力（搜索或知识库），重复“配置→小流量验证→放量”
D4–D5配置邮件与注册策略，建一个普通测试账号从用户视角跑全流程
D7做一次真实恢复演练（隔离环境导入备份）；把发现的问题记入变更日志
首日别做的事

不要第一天就：开放注册、开启高价模型、接入生产支付、把全部工具一次性启用、或同时改环境/网络拓扑。每一步都要有可回退的“上一步快照”（后台配置导出本身就是回退资产）。

首日验收清单​

上线前逐项打勾。每项都给出“通过标准”，不满足就不要引入真实用户：

#验收项通过标准
1管理员登录至少两个管理员账号可独立登录（最好不同登录方式）
2普通用户注册/登录按既定注册策略成功建号并登录；禁用后行为正确
3默认模型对话短问题流式输出完整、无渠道错误
4文件上传一张小图片上传成功并能被视觉模型读取（若声明支持）
5知识库检索上传文本文件、状态到“已完成”、用文件内原句命中引用
6工具调用至少一个已启用工具（如网页搜索）在对话中被正确调用并返回
7停止生成长回答中途点“停止”能立即终止且不产生脏数据
8断线重连生成中刷新页面，回答仍在服务器完成并可回放
9备份导出能生成完整备份 ZIP 并下载到本地
10配置导出保管配置 ZIP（含明文凭据）已放入受控加密存储
11HTTPS 与 Origin正式域名下无混合内容告警；写操作不被 CSRF 拦截
12用量可见“用量”与“用量与计费”出现刚才的测试记录

首次配置常见问题速查​

症状原因处理
打不开 /setup，直接到了登录页实例已有用户，初始化通道已关闭用已有账号登录；忘记密码走“忘记密码”（需 SMTP）
提交初始化返回 409系统已存在至少一个账号正常现象，改用登录
登录成功，但保存任何东西都报“cross-site request blocked”ALLOWED_ORIGINS 未包含浏览器实际访问的源填入不含路径的精确 Origin（逗号分隔）并重启，见域名、HTTPS 与 OAuth
聊天请求报“request signature expired”客户端或代理时钟偏移超出签名窗口NTP 校时；确认代理没有改写 /api 路径
回复一个字都不出 / 流式卡顿后整段弹出反向代理缓冲了 SSE 流代理关闭响应缓冲（见上面同一篇文档）
模型策略页显示“部分已保存的模型策略当前不可用”引用的模型被禁用/删除或渠道失效重选可用模型，再发测试对话
用户侧看不到任何模型模型未启用，或所属渠道被禁用检查渠道“启用”与模型“启用（对用户可见）”两个开关
每次重启就要重新登录（本地开发）未设置 JWT_SECRET，使用随机临时密钥固定一个 ≥32 字符的 JWT_SECRET

下一步​

最后于 更新