基础配置
适用角色：管理员
前置条件：已登录管理员账号
本篇覆盖三项基础配置：机构设置（品牌）、系统配置（键值参数）、数据字典（多语言枚举）。
一、机构设置
机构设置决定所有用户看到的品牌形态。
| 项 | 说明 | 约束 |
|---|---|---|
| 机构 Logo | 显示在登录页中间 | png / jpg / svg / webp，≤ 2MB，建议高度 88px 以上 |
| 欢迎插画 | 聊天页空状态主图 | png / jpg / svg / webp，≤ 2MB，建议宽度 480px 以上 |
| 机构简称 | 显示在登录页 Logo 下方 | 留空则登录页不显示机构名称 |
| 机构全称 | 机构完整名称 | — |
| 操作 | 效果 |
|---|---|
| 上传／删除 Logo | 删除后登录页将不显示 logo |
| 上传／删除欢迎插画 | 删除后聊天页空状态回到默认插画 |
注意 · 机构设置保存在数据库中，跨节点共享。在任意节点改一次，所有节点立即生效。
提示 · 欢迎插画只影响聊天页的空状态（还没有任何对话时的那块区域）。
二、系统配置
系统配置是一组键值对，管理员可增删改。
| 列 | 说明 |
|---|---|
| 配置键 | 唯一标识 |
| 配置值 | 值 |
| 说明 | 用途描述 |
| 更新时间 | — |
2.1 新增配置
| 字段 | 必填 | 规则 |
|---|---|---|
| 配置键 | ✅ | 只能含字母、数字、下划线，如 yuque_key |
| 配置值 | ✅ | — |
| 说明 | ❌ | 配置用途 |
2.2 编辑与删除
2.3 内置配置项
平台自带以下配置项，修改后通常 30 秒内自动生效，无需重启。
| 配置键 | 默认值 | 作用 |
|---|---|---|
access_token_expire_minutes | 60 | 登录令牌有效期（分钟） |
refresh_token_expire_days | 7 | 刷新令牌有效期（天） |
show_session_status | 1 | 是否在账户信息页显示「会话状态」卡片（1 显示／0 隐藏） |
ws_allowed_origins | 空 | WebSocket Origin 白名单扩展 |
public_base_url | 空 | 浏览器视角的公网 base URL |
git_edit_max_file_size | 52428800 | 单文件字节上限（50 MB），0 表示不限 |
关于 ws_allowed_origins
用于 WebSocket 握手时校验 Origin，防 CSWSH（跨站 WebSocket 劫持）。
| 项 | 说明 |
|---|---|
| 基础白名单 | 平台域名 + cell-*.openpartner.com + http://localhost + http://127.0.0.1 |
| 扩展格式 | 逗号分隔，支持 scheme://host[:port] 与 *.example.com 通配子域 |
| 示例 | http://220.112.1.148,http://10.10.6.124,https://*.my-company.com |
| 生效时间 | 30 秒内自动生效 |
注意 · 部署在内网、且前端通过内网 IP 访问时，必须把该地址加入扩展白名单，否则 WebSocket 连不上，表现为「智能体服务连接断开，正在重连」。
关于 public_base_url
用于拼接 AI 生图返回的图片 URL 前缀。
| 场景 | 应填 |
|---|---|
| 用户从公网地址访问平台 | 填公网地址，如 http://220.112.1.148:22053 |
| 仅本机或内网访问 | 可留空，回退到节点自身的 cell_url |
注意 · 该值与节点管理里的「前端→后端 URL」是不同的东西，不要混淆。
三、数据字典
数据字典用于维护枚举值与多语言显示名，供扩展应用与前端读取。
结构分两层：
| 层级 | 说明 |
|---|---|
| 字典类型 | 一组相关枚举值的集合，如「用户状态」「工种」 |
| 字典项 | 类型下的具体条目，如「活跃」「文案」「设计」 |
| 区域 | 内容 |
|---|---|
| 左：字典列表 | 全部字典类型，含名称、标识、说明、状态、项数 |
| 右：字典详情 | 当前选中类型的字典项列表 |
3.1 新建字典
| 字段 | 必填 | 规则 |
|---|---|---|
| 字典名称 | ✅ | 如「用户状态」 |
| 字典标识 | ✅ | 仅英文／数字／下划线，必须以英文开头。创建后不可修改 |
| 说明 | ❌ | — |
| 状态 | — | 启用／禁用 |
注意 · 删除字典会连带删除其下所有字典项，不可恢复。
3.2 字典项
| 字段 | 必填 | 说明 |
|---|---|---|
| 项编码 | ✅ | 唯一标识 |
| 显示名（中文） | 至少一种 | 界面上显示的文字 |
| 显示名（英文） | 至少一种 | 如 Active |
| 实际值 | ❌ | 留空默认等于项编码 |
| 排序 | ❌ | 数字越小越靠前 |
提示 · 字典项的「显示名」与「实际值」可以不同：显示名给人看，实际值给程序用。
四、常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 登录页没有机构名 | 机构简称留空 | 在机构设置填写 |
| 聊天页空状态是默认插画 | 未上传欢迎插画 | 上传自定义插画 |
| WebSocket 一直重连 | ws_allowed_origins 未包含实际访问地址 | 加入扩展白名单 |
| 修改配置后没生效 | 部分改动有缓存延迟 | 等待约 30 秒；仍无效则检查配置键是否拼错 |
| 字典标识改不了 | 设计如此，创建后不可修改 | 需要变更请新建字典 |
| 删字典后数据没了 | 字典项随类型一并删除 | 删除前确认 |
五、相关页面
| 页面 | 内容 |
|---|---|
| 模型厂商接入 | 平台最优先级的配置 |
| 集成配置 | Git 仓库与凭证 |
| 节点与升级 | public_base_url 与节点 URL 的区别 |