系统、备份与运营
本文档基于 Aivory v2.4.7 及发布后的 main 分支编写。涉及“系统”导航组（公告、邮件服务、存储与上传、法律与联系、日志与隐私、备份与迁移）与“数据与运营”页签、“能力与集成”下的内容审核与语音，以及独立的域名/工作空间管理页面。
系统设置决定实例如何发送邮件、保存对象、记录日志、展示法律信息和执行备份；运营页面帮助管理员观察用户、模型、文件与反馈。把它们当作持续运维，而不是安装时填一次就结束。
管理后台地图
| 导航组 | 页签 | 本文相关小节 |
|---|---|---|
| AI 与模型 | 内容审核 | 内容审核与语音 |
| 能力与集成 | 语音 | 内容审核与语音 |
| 系统 | 公告 / 邮件服务 / 存储与上传 / 法律与联系 / 日志与隐私 / 备份与迁移 | 以下各节 |
| 数据与运营 | 用量与计费 / 用量 / 内容资源 / 文件 / 用户反馈 | 运营节奏 |
组织访问单独记录在域名入组与工作空间访问。/admin/workspaces 用于创建工作空间和更换负责人，/admin/domains 用于精确邮箱域入组及个人空间锁定；不要用全局邮箱白名单替代这些规则。
邮件服务
“系统 → 邮件服务”配置 SMTP：主机、端口、用户名、密码、发件地址与 TLS 方式，并可调整验证/重置邮件模板。邮件支撑注册邮箱验证（6 位验证码，10 分钟有效）、忘记密码与运营通知，面向真实用户的部署应尽早配置。
| 字段 | 说明 | 示例 / 默认 |
|---|---|---|
| 主机 / 端口 | SMTP 服务器地址与端口 | smtp.example.com；465 或 587 按服务商 |
| 用户名 / 密码 | 登录凭据；优先使用应用专用密码 | 服务商提供 |
| 发件地址 | 收件人看到的 From，应属受控域名 | no-reply@aivory.example.com |
| TLS 方式 | 直接 TLS（隐式 SSL，常配 465）或 STARTTLS（常配 587） | 按服务商文档 |
| 邮件模板 | 验证 / 重置邮件的标题与正文 | 默认模板可先上线 |
配置要求与验证：
- 使用服务商提供的 SMTP 凭据或应用专用密码，不复用管理员登录密码。
- 发件地址属于受控域名，并在 DNS 配置 SPF、DKIM、DMARC 或完成服务商域名验证——否则验证码邮件大概率进垃圾箱。
- 区分直接 TLS（隐式 SSL）与 STARTTLS 所需端口，按服务商文档填写。
- 保存后用非管理员测试邮箱验证：收信、验证码登录、重置密码全流程。
未配置时，“要求邮箱验证”与“忘记密码”功能实际不可用。排查时不要在公开日志里打印验证码或 SMTP 密码。
邮件故障速查
| 症状 | 优先检查 |
|---|---|
| 保存后测试连接失败：connection refused | 端口与 TLS 模式不匹配（465 直接 TLS vs 587 STARTTLS） |
| 认证失败 535 | 用了网页登录密码而不是应用专用密码；账号开启二次验证 |
| 验证码邮件进垃圾箱 | 发件域 SPF/DKIM/DMARC 未配；发件地址与登录身份不一致 |
| 用户说没收到，日志显示已发送 | 收件方网关拦截；引导用户加白名单，或换发件域 |
| 验证码正确但提示无效/过期 | 10 分钟 TTL 与 5 次尝试上限；用户反复点“重发”会作废旧码，属预期 |
存储与上传
“系统 → 存储与上传”集中管理对象存储、归档保留与上传策略（RAG 侧的边界见知识库、RAG 与存储）：
| 区块 | 关键字段 | 说明 |
|---|---|---|
| 对象存储 | 存储类型（本地 / S3 / 阿里云 OSS）、endpoint、bucket、前缀、AccessKey | 默认本地：头像等对象写入本地对象目录，上传与产物在 DATA_DIR。多副本、跨节点或需要 MinerU 时改用受控对象存储 |
| 上传策略 | 图片大小上限（默认 5 MB）、非图片文件上限、允许扩展名 | 均不能超过服务器硬上限 MAX_UPLOAD_BYTES（默认 50 MiB）；扩展名留空 = 安全默认集 |
| 沙盒归档 | 归档保留天数 | 默认 30 天；决定持久工作区 tar 的存活期 |
| 向量维护 | 检查 / 重建入口 | 与“备份与迁移”的向量检查同源 |
| 存储清理 | 待清理对象视图 | 删除用户/文件后的异步物理清理在此观察 |
对象存储使用单独的最小权限账号：只授予所需 bucket/prefix 的读写与预签名，不给云账号管理员权限；设定生命周期、版本控制、加密与访问日志。更换 endpoint、bucket、区域或密钥后，逐项测试上传、下载、预览、解析、分享快照与删除，再迁移真实文件。
日志与隐私、法律与联系
“系统 → 日志与隐私”控制请求日志的详细程度（对应运行时设置键 log_full_requests / log_errors_only / log_request_bodies）：是否记录完整请求、是否只记错误、是否记录请求体。原则：
- 不记录模型服务商 API Key、OAuth Client Secret、支付签名、JWT、刷新令牌、完整用户文件或完整私密提示词（脱敏由日志策略保证，开关越详细风险越高）。
- 排查优先使用时间、请求 ID、脱敏错误码与聚合指标；“用量”页的逐条请求诊断字段已是脱敏版本。
- 为日志设定留存与访问权限；日志导出同样可能包含用户元数据。
- 数据导出、删除、备份恢复和第三方传输要有负责人与审批流程。
“系统 → 法律与联系”维护服务条款、隐私政策与运营者联系入口。公开服务应提供真实可处理的联系信息和与实际数据流一致的隐私说明（例如启用了 MinerU/外部搜索时说明数据出境路径）。
公告与内容运营
“系统 → 公告”维护一条全局公告（用户打开应用时显示）：
| 字段 | 说明 | 限制 |
|---|---|---|
| 显示公告 | 总开关，关闭即清空所有展示 | — |
| 必须阅读 | 用户需等待 5 秒才能关闭或选择不再提示 | — |
| 允许“下次不再提示” | 关闭后每次访问都会重新弹出 | — |
| 标题 | 纯文本 | ≤120 字符 |
| 图片 | 链接或上传 PNG/JPG | ≤256 KB |
| 文字 | 支持 HTML，换行用 <br> | 发布前用预览 |
发布前用测试账号检查展示范围、关闭行为与移动端排版；紧急公告避免嵌入敏感内部信息或无法验证的外部脚本。提示词、技能、图片风格等面向全体用户的改动先小范围验证、保留快速禁用/回退路径。
内容审核与语音
内容审核（“AI 与模型 → 内容审核”）在生成前审核每条用户提示（不含历史）；开关本身在模型编辑页按模型启用，模式选关键词或审核模型：
| 字段 | 说明 |
|---|---|
| 违规关键词 | 每行一个，命中即拦截 |
| 审核模型 | “模型”模式下做放行/拦截判定的模型 |
| 违规类型 | 每行一个类别（如政治、色情、暴力），供模型审核参考 |
| 拦截提示语 | 被拦截时向用户显示的文字 |
语音（“能力与集成 → 语音”）配置输入框麦克风的语音转文字，两种渠道：
| 渠道 | 特点 | 凭据 |
|---|---|---|
| OpenAI 兼容（Whisper） | 先录音再转写 | Base URL（默认 https://api.openai.com）、模型（如 whisper-1）、API Key |
| 火山引擎 · 豆包（实时流式） | 边说边出字，基于 WebSocket 的实时 ASR | App ID、Access Token、Resource ID（默认小时版）、可配标点/数字规整/语义顺滑 |
API Key / Access Token 留空即禁用语音输入；用户组权限中的“语音识别”控制谁可用。
备份与迁移
“系统 → 备份与迁移”提供四类能力，风险和用途各不相同：
| 类型 | 内容 | 用途 | 安全级别 |
|---|---|---|---|
| 导出备份 | 全库 + 可选 uploads/artifacts + Qdrant 向量的 ZIP 归档（异步生成，显示步骤进度） | 灾难恢复、跨服务器与 SQLite↔PostgreSQL 迁移、恢复演练 | 高敏感 |
| 导入与还原 | 上传导出的归档，替换本部署全部数据 | 恢复/迁移落地 | 危险操作 |
| 向量检查 | 比对数据库切块与向量库（应有/正常/缺失/空向量/跳过），可只重建缺失部分 | RAG 完整性巡检 | 低 |
| 导出/导入配置 | 站点设置、渠道、模型、技能、OAuth、图片风格、用户组、额度与资产的 ZIP | 复制受控环境、变更留档 | 包含密钥明文 |
完整备份 ZIP 的边界要心中有数：
| 归档包含 | 归档不包含 |
|---|---|
| 全部数据表（用户、对话、文件记录、积分、订单、Passkey 和域名绑定等 60 表） | 环境变量（JWT_SECRET、DATABASE_URL 等——恢复后仍需在部署环境配好） |
| 可选：uploads 与 artifacts 文件 | Redis 缓存（设计上可丢弃重建） |
| 完整版：Qdrant 向量 | 正在运行的沙盒容器与工作区（未归档的活跃会话） |
| 导出过程分步进度（准备/读库/写归档） | 宿主机系统配置与反向代理配置 |
导入前系统要求逐字输入确认词。还原完成后所有会话失效，当前管理员会被登出并需使用导入数据中的账号重新登录。执行前先停写入、保留现有数据副本；恢复后检查管理员登录、普通对话、附件、知识库状态、向量检索、对象存储访问、OAuth 与邮件。docker compose down -v 会删除命名卷，绝不是普通重启命令。
“导出配置 ZIP”包含渠道 Key、OAuth Secret、SMTP、支付与存储凭据明文。加密保存、限制访问，不要进版本控制或工单附件。
个人版整体备份 DATA_DIR 即可；完整版必须把 PostgreSQL、Redis、Qdrant、沙盒归档卷与 DATA_DIR 当作一个一致性备份单元。命令级流程与恢复顺序见升级、备份与恢复。
运营节奏与主机监控
“数据与运营”提供内容资源（全平台知识库/项目/生成图片）、文件（删除会同时清除记录、向量与磁盘文件）、用户反馈（含可选截图与对话快照）与用量视图。建议建立固定节奏：
- 每日/每周检查错误率、模型失败、支付异常和高成本用户/模型。
- 审阅增长趋势、存储占用、知识库任务积压与异常大文件。
- 把用户反馈关联到实际会话、模型、渠道或配置，但避免把私密内容复制进公开工单。
- 清理测试文件、废弃模板和过期兑换码前确认备份与保留规则。
- 向量重建、批量删除、导入/导出等长任务先观察进度结果，再发起下一轮。
运营页面提供观察与管理能力，不替代主机级监控。
监控指标速查
| 指标 | 告警参考 | 第一响应 |
|---|---|---|
磁盘余量（DATA_DIR、pgdata、qdrantdata、redisdata） | < 15% | 清理测试文件/过期归档，扩盘 |
| 模型错误率（“用量与计费”按渠道切分） | 单渠道连续错误 > 5% | 禁用该渠道或切换默认模型（模型策略可即时改） |
| 知识库任务积压（failed 计数上升） | 持续增长 | 检查 embedding/MinerU 服务与额度，必要时先关注册 |
| 沙盒 500 突增 | 伴随 image pull 日志 | 恢复 keepalive 镜像，勿放大超时 |
| 备份任务成功率 | 任何一次失败 | 在修复前视实例为“无备份”状态，禁止高危变更 |
| TLS 证书剩余天数 | < 21 天 | 续签；OAuth/webhook 同时受影响 |
| 容器重启次数 | 非零增长 | 看 OOM 与 JWT_SECRET/配置错误类崩溃循环 |
发现趋势异常时先限制风险能力或用户范围（全局工具禁用、注册关闭、组配额下调），再做根因排查。
部署级运行参数速查
日常运维最常碰的环境变量（完整清单见环境变量进阶）：
| 变量 | 作用 | 默认 |
|---|---|---|
JWT_SECRET | 会话签名主密钥；≥32 字符，部署环境必设 | 无（开发模式随机生成） |
ACCESS_TTL / REFRESH_TTL | 访问 / 刷新令牌有效期 | 30m / 720h |
MAX_UPLOAD_BYTES | 上传请求体硬上限 | 50 MiB |
MAX_BACKUP_BYTES | 备份归档大小上限 | 20 GiB |
AIVORY_HTTP_IDLE_TIMEOUT | 空闲连接超时；默认 20 分钟刻意大于 Cloudflare 约 15 分钟的回源复用窗口，避免用户看到“无法访问此网站” | 20m |
AIVORY_API_MAX_GEN_DURATION | 单轮生成的最长执行时间；浏览器断线不会中止服务器端生成 | 90m |
AIVORY_REQUEST_SIGNATURES_REQUIRED | 认证写操作的 HMAC 签名开关；仅调试时关闭 | true |
“系统”导航组各页与“数据与运营”看板暂无随发行版提供的截图；页面均为标准表单/列表布局。