Repository navigation
Configuration
本文档说明管理后台"设置"页面中实际可配置的项目，按分组整理，并标注每项的用途、是否必填、修改后是否需要重启服务才能生效。具体是否显示某一项，取决于你的账号角色和版本；密钥类字段（Secret）在页面上始终以掩码形式展示，不会回显明文。云托管版与自托管版的商业额度不同，详见版本说明。
- 设置页会显示每一项当前的取值来源：数据库中已保存的值 > 环境变量 > 系统默认值，三者按优先级依次生效。在设置页保存过的值优先于部署环境变量。
- 密钥类字段（如各类 Secret/密钥）留空提交时，系统会将其视为"不修改"，不会清空或覆盖已保存的密钥，这是刻意设计，避免误操作导致密钥被清空。
- 保存设置后，大多数配置项会立即生效，无需重启；只有极少数底层存储相关配置需要重启服务才能生效（见下文"存储配置"分组中的标注）。
- 设置页提供"测试连接"功能，可以针对企业微信、七牛云（Qiniu）存储、自定义域名分别做一次连通性检查，检查结果只返回是否成功，不会回显具体的密钥内容。
| 配置项 | 用途 | 是否必填 | 修改后是否需重启 |
|---|---|---|---|
| 管理后台域名（admin_domain） | 系统对外可访问的管理后台域名，用于企业微信 OAuth 登录跳转、导出通知邮件中的链接生成等场景 | 否 | 否 |
当前邮件发送入口读取部署环境变量，不读取此页面保存的数据库 SMTP 值，
因此在此保存字段不代表邮件配置已生效。自托管部署者应通过受保护的环境配置提供
EMAIL_PROVIDER 及所选邮件服务需要的凭据和发件地址；不要把 API Key、SMTP 密码或其他密钥提交到仓库或支持请求中。缺少有效发送配置时，邮件发送会失败，依赖邮件的功能可能不可用。
| 配置项 | 用途 | 是否必填 | 修改后是否需重启 |
|---|---|---|---|
| SMTP 服务器地址（smtp_host） | 邮件发送服务器地址 | 否（但为功能所需） | 否 |
| SMTP 端口（smtp_port） | 邮件发送服务器端口 | 否 | 否 |
| SMTP 用户名（smtp_user） | 邮件服务鉴权用户名 | 否 | 否 |
| SMTP 密码（smtp_password） | 邮件服务鉴权密码（密钥类字段，掩码展示） | 否 | 否 |
| 发件邮箱（smtp_from） | 系统发出通知邮件时显示的发件地址 | 否 | 否 |
用于系统与企业微信之间建立会话存档同步与登录授权所需的核心凭据。这一组内的字段大多为必填，缺失会导致同步/登录相关功能不可用。
| 配置项 | 用途 | 是否必填 | 修改后是否需重启 |
|---|---|---|---|
| 企业 ID（wecom_corp_id） | 企业微信官方分配的企业 CorpID，用于识别本企业并解析归档消息的所属企业 | 是 | 否 |
| 应用 ID（wecom_agent_id） | 企业微信自建应用的 AgentID，用于 OAuth 登录等场景 | 是 | 否 |
| 应用密钥（wecom_oauth_secret） | 企业微信自建应用的 Secret（密钥类字段，掩码展示） | 是 | 否 |
以上参数一般在完成企业微信授权/接入配置时由系统或管理员填写，具体获取方式请参见企业微信接入与常见错误。修改这组配置后无需重启服务即可生效，但如果填写有误会直接影响同步和登录功能，建议修改后使用"测试连接"功能验证，并关注同步状态是否恢复正常。
回调 Token 与回调加密 AES Key 不在本页配置。 这两项属于租户级归档凭据，在租户配置向导（自托管为 /admin/provisioning/settings，云托管为企业微信授权开通流程）中随归档凭据一并录入和验证；系统在落库前对其加密，数据库中仅保存密文，页面不回显明文，因此它们不属于"设置"页的可配置项。
用于配置媒体文件（图片、语音、视频、文件）的存储后端。默认使用本地磁盘存储；如需切换到七牛云（Qiniu Kodo）对象存储，需要额外填写对应的 Qiniu 参数。
| 配置项 | 用途 | 是否必填 | 修改后是否需重启 |
|---|---|---|---|
| 媒体存储提供方（media_storage_provider） | 选择新写入媒体使用的存储后端（本地磁盘或七牛云） | 否 | 是 |
| 存储后端（storage_backend） | 与上一项配合使用的存储后端选择器 | 否 | 是 |
| 七牛 Access Key（qiniu_access_key） | 七牛云访问密钥（密钥类字段），仅当媒体存储提供方选择七牛云时需要 | 否（选择七牛云时实际必需） | 否 |
| 七牛 Secret Key（qiniu_secret_key） | 七牛云访问密钥对应的私钥（密钥类字段） | 否（选择七牛云时实际必需） | 否 |
| 七牛存储空间（qiniu_bucket） | 七牛云对象存储的 Bucket 名称 | 否（选择七牛云时实际必需） | 否 |
| 七牛访问域名（qiniu_domain） | 用于生成媒体访问地址的域名，必须是完整的 https:// 地址 |
否（选择七牛云时实际必需） | 否 |
| 七牛区域（qiniu_region） | 七牛云存储所在区域，用于部分接口的区域路由 | 否 | 否 |
重要提示：切换"媒体存储提供方"只影响之后新下载的媒体使用哪个存储后端，不会把已经存在的历史媒体文件迁移到新后端，也不会影响已有记录的正常读取——每条媒体记录会一直使用它当初写入时所用的存储后端。这两项修改后需要重启服务才能生效,这是刻意设计的行为,避免运行中的任务在存储配置切换中途出现不一致。
以下为媒体处理相关的精细化参数，通常保持默认值即可，仅在有特定需求（例如带宽/存储成本优化、下载重试策略调整）时才需要调整。修改后均无需重启。
| 配置项 | 用途 | 是否必填 | 默认值 |
|---|---|---|---|
| 生成缩略图（media_thumbnail_enabled） | 是否为图片消息生成列表用小缩略图，用于加快会话列表加载速度 | 否 | 视部署而定 |
| 缩略图最大边长（media_thumbnail_max_edge） | 生成缩略图时的最大边长（像素） | 否 | 视部署而定 |
| 缩略图 JPEG 质量（media_thumbnail_jpeg_quality） | 生成 JPEG 格式缩略图时的压缩质量 | 否 | 视部署而定 |
| 语音转码（voice_transcode_enabled） | 是否将语音消息转码为更通用的播放格式，便于在浏览器中直接播放 | 否 | 视部署而定 |
| 事件触发媒体下载开关（event_media_download_enabled） | 是否在归档同步完成后自动触发一次媒体下载 | 否 | 开启 |
| 事件触发批量上限（event_media_download_batch_limit） | 单次事件触发媒体下载处理的最大消息数 | 否 | 20 |
| 新鲜媒体时间窗口（event_media_download_recent_window_hours） | 事件触发时优先处理多少小时内的新媒体 | 否 | 24 小时 |
| 失败重试次数上限（event_media_download_retry_count） | 一条媒体下载失败后最多自动重试的次数 | 否 | 3 次 |
| 重试退避基数（event_media_download_backoff_seconds） | 失败重试之间的退避等待时间基数（秒） | 否 | 30 秒 |
| 事件触发清扫间隔（event_media_download_sweep_interval_seconds） | 事件触发媒体下载的清扫扫描间隔（秒） | 否 | 15 秒 |
系统首次启动、尚未完成任何配置时，会提供一个一次性的初始化入口，用于填写管理员账号（密码登录模式下）和基础的企业微信参数（企业 ID、应用 ID、应用密钥）。该入口只能使用一次，完成初始化后会自动关闭，不会覆盖之后在正常设置页所做的修改。对于通过企业微信授权自助开通的客户，这一步通常已经在开通流程中自动完成，无需额外操作。
本文档基于系统当前的可配置项整理，第一版可能未覆盖未来新增的配置分组。如果设置页面中出现本文档未列出的新配置项，请以页面上的说明文案为准，或联系客服确认具体用途。