系统设置
这一篇覆盖 管理 -> 系统设置 里的所有分组
系统设置是管理员在后台直接维护的全站规则。按分组跳到你关心的那一节就行，不必从头读。 大多数改动不需要重启服务，保存后会影响后续新请求、新上传、新发出的邮件。
入口：
管理 -> 系统设置先按目标定位
| 目标 | 先看分组 | 如果还是不对 |
|---|---|---|
| 站点链接、分享链接、邮件链接域名不对 | 站点配置 | 再看 反向代理 |
| 登录 Cookie、Token、激活链接时效不合适 | 认证与 Cookie | 再看 登录与会话 |
| 注册、头像、Gravatar 行为不符合预期 | 用户管理 | 再看 管理后台 |
| Passkey、MFA、外部登录、外部身份绑定不符合预期 | 站点配置 / 管理 -> 外部认证 / 认证与 Cookie | 再看 登录与会话 |
| 邮件收不到或链接不对 | 邮件投递 | 再看 邮件 |
| 跨源页面调用 API 被浏览器拦 | 网络访问 | 先确认不是 公开站点地址 问题 |
| 后台任务、缩略图、ZIP 预览、回收站保留策略异常 | 运行与调度 / 存储与保留 | 再看 运维 CLI |
| 分享页视频/音频播放链接过期太快或太慢 | 运行与调度 | 再看 分享与公开访问 |
| WebDAV 总开关或行为异常 | WebDAV | 再看 WebDAV |
| 要查谁改了什么 | 审计日志 | 再看 管理后台 |
管理员最常改的地方
| 你想做什么 | 去哪里改 |
|---|---|
| 让分享链接、邮件链接、WebDAV 地址、在线预览都指向正确域名 | 站点配置 -> 公开站点地址 |
| 改登录页和分享页显示的标题、Logo、favicon | 站点配置 |
| 给 Office 文件加外部预览或 WOPI 打开方式 | 站点配置 -> 预览应用 |
| 开启或限制 ZIP 压缩包只读预览 | 存储与保留 -> 压缩包预览 |
| 接入 OIDC / SSO 登录提供商 | 管理 -> 外部认证 |
| 关闭公开注册 | 用户管理 -> 允许公开注册新用户 |
| 改新用户默认配额（创建团队后再核对实际团队配额） | 存储与保留 -> 新用户默认存储配额 |
| 调 Cookie 安全要求、Access / Refresh Token 有效期 | 认证与 Cookie |
| 调激活、改绑、密码重置链接有效期 | 认证与 Cookie |
| 调外部登录邮箱验证邮件模版 | 邮件投递 -> 外部登录邮箱验证 |
| 配 SMTP、发测试邮件、改事务邮件模版 | 邮件投递 |
| 调回收站、历史版本、团队归档、任务产物保留时间 | 存储与保留 |
| 调在线解压临时空间上限 | 存储与保留 -> 在线解压 staging 大小上限 |
| 调缩略图大小限制、vips / ffmpeg / ffprobe 处理器 | 存储与保留 -> 媒体处理 |
| 关闭 WebDAV | WebDAV -> 启用 WebDAV |
| 调邮件派发、后台任务派发、并发、重试、周期清理频率 | 运行与调度 |
| 调分享页音频/视频流播放临时会话有效期 | 运行与调度 -> 分享流播放会话有效期 |
| 开关审计日志 | 审计日志 |
当前有哪些分组
- 站点配置 —— 公开站点地址、标题、Logo、favicon、预览应用
- 用户管理 —— 公开注册、注册激活、头像、Gravatar
- 认证与 Cookie —— Cookie 安全规则、Token 有效期、激活/改绑/重置链接有效期
- 邮件投递 —— SMTP、发件人、测试邮件、注册激活/改绑/密码重置/外部登录邮箱验证邮件模版
- 网络访问 —— 浏览器跨站访问规则（CORS）
- 运行与调度 —— 邮件队列、后台任务、任务车道并发、分享流播放 session、周期清理、底层一致性检查、远程节点健康检测、列表上限
- 存储与保留 —— 回收站、历史版本、默认配额、任务产物、在线解压 staging、ZIP 压缩包预览、媒体处理
- WebDAV —— 总开关
- 审计日志 —— 开关和保留时间
- 自定义配置、其他 —— 高级场景才碰
站点配置
如果站点要对外访问，先把这一组配对。
公开站点地址填用户真正访问站点的 HTTP(S) 来源，在列表里每个输入框填一个，例如：texthttps://drive.example.com https://panel.example.com每一项只填到来源层：协议、域名和可选端口。不要带路径，不要带
/api，也不要写通配符。系统会用这些来源生成分享页、邮件链接、WebDAV 地址、Office / WOPI 预览和后续回调所需的绝对 URL。留空时浏览器页面多数能按当前访问地址工作，但外部入口更容易生成错链接。正式部署建议明确配置公开站点地址。如果同一个实例通过多个域名访问，全部填进这个列表。AsterDrive 会根据当前请求的 Host 在列表里找精确匹配的来源；匹配上就用对应来源生成链接，匹配不上时使用第一项作为回退来源。
这不是 CORS 白名单
公开站点地址表示“哪些公开入口属于这个 AsterDrive 实例”，也会参与 Cookie 写操作的 same-site CSRF 信任判断。它不会自动允许浏览器跨域调用 API。跨域访问仍然在网络访问 -> 允许跨域来源里单独配置。站点标题、站点描述影响登录页、分享页、应用页的标题与描述。favicon、浅色 Logo、深色 Logo 影响浏览器标签页、登录页、站点头部的品牌显示。预览应用给 Office、PDF、表格或其他文件提供额外的"打开方式"。内置预览器、外部 URL 模板、WOPI 打开方式在这里统一管理。WOPI 相关时效只有接入 OnlyOffice 一类在线 Office 预览/编辑服务时才需要调。普通部署保持默认。
启用 WOPI 的推荐顺序
- 先填对
公开站点地址 - 到
预览应用里启用已有应用，或通过WOPI Discovery导入新应用 - 确认外部 Office / WOPI 服务能回连到
公开站点地址生成的/api/v1/wopi/... - 如果浏览器跨源调用 AsterDrive API 被拦，再去
网络访问放行对应来源 - 用真实的
docx/xlsx/pptx试开一次，确认能保存回 AsterDrive
WOPI access token 有效期、WOPI 锁有效期、WOPI discovery 缓存时长 都在这一组里。只有在你已经接了 WOPI 服务、并且确实碰到会话过期或 discovery 更新不及时这类问题时，才需要手动调整。
用户管理
这一组控制账号入口和头像相关行为。
允许公开注册新用户—— 关闭后登录页只剩已有账号登录和管理员初始化；新增账号只能管理员创建注册后要求邮件激活—— 开启后公开注册的普通用户必须先点激活邮件才能登录头像目录—— 用户上传头像写到这个本地目录。相对路径解析到服务端./data下头像上传大小上限—— 超过的头像文件直接被拒Gravatar 基础地址—— 访问官方 Gravatar 不稳定时，换成代理或镜像
认证与 Cookie
这一组决定浏览器登录体验和会话安全。
认证 Cookie 仅 HTTPS 发送—— 正式环境保持开启。只有本地或内网纯 HTTP 试跑时才临时关访问令牌有效期、刷新令牌有效期—— 控制登录态维持多久注册激活链接有效期邮箱改绑链接有效期密码重置链接有效期验证邮件重发冷却时间密码重置请求冷却时间
正常部署多数时候只需要确认 Cookie 安全要求和链接时效符合你的站点策略。
邮件投递
这一组决定注册激活、密码重置、邮箱改绑邮件能不能发出去。最常改的：
- SMTP 主机、端口、用户名、密码
- 发件人地址、发件人名称
- 是否启用 SMTP 加密
- 测试邮件
- 注册激活、密码重置、邮箱改绑、外部登录邮箱验证邮件模版
准备开放注册前先检查
如果站点要开放注册、找回密码或邮箱改绑，邮件配置和 公开站点地址 要一起检查，避免只配置其中一项。
外部认证里如果允许通过邮箱验证继续完成绑定或创建账号，也同样依赖这一组邮件配置。
详细指引见 邮件。
网络访问
这一组主要是浏览器跨站访问规则（CORS）。
只在这些场景才需要改：
- 浏览器页面和 AsterDrive 不在同一个域名下
- 想让别的站点在浏览器里直接调用 AsterDrive
同站部署一般不用动
大多数"前端页面和接口都在同一个站点里"的部署不需要碰这里。
接外部 WOPI 服务时，最常见的问题不是这里，而是 Office 服务回连不到 公开站点地址 生成的 WOPI URL。只有当浏览器控制台明确报 AsterDrive API 的 CORS 错误时，才需要把对应来源加到这里。
运行与调度
管理员在这里决定后台任务的节奏。默认行为：
| 任务 | 默认频率 |
|---|---|
| 邮件队列扫描 | 每 5 秒 |
| 后台任务队列扫描 | 每 5 秒 |
| 后台任务空闲退避上限 | 每 60 秒 |
| 周期性清理 | 每 1 小时 |
| 底层文件一致性检查 | 每 6 小时 |
| 系统健康检测（数据库 / 缓存 / 远程节点） | 每 5 分钟 |
还能在这里调：
- 后台任务空闲退避上限
- 默认后台任务并发上限
- 在线压缩、在线解压、ZIP 预览这一组归档任务的并发上限
- 缩略图生成任务并发上限
- 后台任务最大尝试次数
- 分享下载回滚队列容量
- 分享流播放 session 有效期
- 系统健康检测间隔
- 团队成员列表单页上限
- 任务列表单页上限
没明显的性能、队列积压或远程节点探测延迟问题，保持默认就够了。
如果你把后台任务并发调大，在线压缩、在线解压、ZIP 预览和缩略图任务会更容易同时跑起来，CPU、内存和 I/O 压力也会一起上来。
分享页里的音频和视频为了支持 Range 播放，会先创建一个短时效流播放 session。默认有效期是 3 小时，可配置范围是 5 分钟到 24 小时。调长更适合长时间后台播放音乐；调短可以缩小链接泄漏后的可访问窗口。
存储与保留
这一组决定"数据留多久"和"新对象默认拿多少空间"。默认规则：
| 项目 | 默认值 |
|---|---|
| 单文件历史版本上限 | 10 |
| 回收站保留时长 | 7 天 |
| 团队归档保留时长 | 7 天 |
| 任务保留时长 | 24 小时 |
| 新用户默认存储配额 | 0（不限制） |
| 在线解压 staging 大小上限 | 2 GiB |
| ZIP 压缩包预览总开关 | 关闭 |
| ZIP 压缩包预览用户侧开关 | 关闭 |
| ZIP 压缩包预览分享侧开关 | 关闭 |
| ZIP 压缩包预览源文件大小上限 | 64 MiB |
| ZIP 压缩包预览条目数量上限 | 2000 |
| ZIP 压缩包预览 manifest 大小上限 | 64 KiB |
| ZIP 压缩包预览扫描耗时上限 | 30 秒 |
| 缩略图源文件大小上限 | 64 MiB |
默认配额只影响新对象
- 界面里这一项的名称就是
新用户默认存储配额 - 团队创建后的实际配额，建议到
管理 -> 团队里再核对一次 - 这个设置只影响之后新创建的对象；已存在的账号或团队不会被自动回写
ZIP 压缩包预览
压缩包预览是只读功能，只扫描 ZIP 的目录清单并生成 manifest，不会把压缩包解开到用户文件夹里。它和“在线解压”不是一回事。
这一组里有三层开关：
- 启用 ZIP 压缩包预览：总开关
- 对用户启用 ZIP 预览：登录用户在个人空间和团队空间里能不能预览
- 对分享启用 ZIP 预览：公开分享页在通过密码和分享范围校验后能不能预览
默认三项都是关闭。建议只有在确实需要用户查看 ZIP 内部清单时再打开，尤其是分享侧开关；它会让访问者看到压缩包内部的文件名、目录结构、大小和修改时间这类元数据。
限制项控制源 ZIP 大小、条目数量、返回 manifest 大小和单次扫描耗时。第一次打开某个 ZIP 时，如果清单还没有缓存，系统会创建 archive_preview_generate 后台任务；生成完成后再次打开会直接复用缓存。
用户在预览工具栏切换 文件名编码 时，会按所选编码重新读取或生成清单。这个能力用于处理旧 ZIP 或跨语言环境生成的 ZIP 文件名乱码，不会修改原始压缩包。
媒体处理
媒体处理这一块负责缩略图生成，不负责在线预览本身。
它现在在 存储与保留 -> 媒体处理 里有结构化编辑器，不需要手改 JSON。
你可以在那里做这些事：
- 开关某个处理器
- 给处理器绑定文件后缀
- 配置
vips_cli、ffmpeg_cli或ffprobe_cli使用的命令 - 测试命令是否能被服务端执行
- 保留 AsterDrive 内置图片处理器作为兜底
默认内置链路覆盖常见图片格式。
如果你想给 HEIC、AVIF、PDF 封面、视频缩略图或视频元数据扩展能力，可以接 vips、ffmpeg 或 ffprobe，但前提是这些命令真的装在服务端环境里。
建议先保留内置处理器
除非你已经确认 vips / ffmpeg / ffprobe 的命令路径、权限和后缀绑定都没问题，否则保留内置处理器当兜底更省心。
首次启动时的媒体处理 ENV
服务第一次初始化系统设置时，会读取三个 bootstrap 环境变量，用来决定媒体处理默认配置里是否启用 CLI 处理器：
ASTER_BOOTSTRAP_ENABLE_VIPS_CLI=true
ASTER_BOOTSTRAP_ENABLE_FFMPEG_CLI=true
ASTER_BOOTSTRAP_ENABLE_FFPROBE_CLI=true官方 Docker 镜像已经安装 vips、ffmpeg 和 ffprobe，并默认打开这三个 bootstrap ENV，所以新库通常会直接带上对应处理器。
这三个变量只影响 media_processing_registry_json 还不存在时的初始默认值。这个规则表是统一媒体处理配置入口，用来管理内置 images、内置 lofty、VIPS CLI、FFmpeg CLI、FFprobe CLI 的启用状态、能力用途、后缀绑定和命令路径；缩略图和媒体元数据都会走这条链路。
媒体元数据
媒体元数据和缩略图共用 media_processing_registry_json：
media_metadata_enabled是总开关media_metadata_max_source_bytes限制进入元数据后台任务的源文件大小images处理器启用且具备metadata:image用途时，负责图片元数据lofty处理器启用且具备metadata:audio用途时，负责音频元数据；具备thumbnail:audio用途时，负责从音频内嵌封面生成 WebP 缩略图ffprobe_cli处理器启用且具备metadata:video用途时，负责视频元数据；它的config.command可以是命令名或绝对路径
如果服务端的 ffprobe 改名了、没放进 PATH，或者需要指定自定义安装路径，把 media_processing_registry_json 里 ffprobe_cli.config.command 改成对应命令或绝对路径，然后在媒体处理注册表里执行 test_ffprobe_cli 探测。
WebDAV
这里目前最重要的就是：
启用 WebDAV
关闭后桌面客户端会立刻无法继续通过 WebDAV 访问文件。
请到站点配置分组调整改路径前缀
如果你只是想改 WebDAV 路径前缀或 WebDAV 上传体积硬上限，那不在这一页，而是在 config.toml 的 [webdav] 里改，改完要重启。
审计日志
这一组决定后台和关键操作是否留下记录。
启用审计日志审计日志保留时长
不建议轻易关闭
想之后还能追查"谁删了文件、谁创建了分享、谁改了团队成员"，建议保持开启。
修改后什么时候生效
| 改动 | 生效时机 |
|---|---|
| 站点地址、标题、Logo、favicon | 刷新页面后按新值显示 |
| 预览应用 / 在线 Office 相关 | 之后新打开的预览按新规则 |
| WOPI access token / 锁 / discovery 缓存 | 之后新开的 WOPI 会话按新规则 |
| 公开注册、注册激活、邮件模版 | 之后新进入登录流程、新发出的邮件按新规则 |
| 外部登录提供商 | 保存后登录页和后续外部登录流程按新规则 |
| 外部登录邮箱验证邮件模版 | 之后新发出的外部登录验证邮件按新规则 |
| Cookie 安全、Token 有效期 | 之后新登录、刷新、分享密码验证按新规则 |
| 头像目录、头像上限 | 之后新上传头像按新规则 |
| 默认配额 | 只影响之后新创建的对象 |
| 回收站、团队归档、任务产物、审计日志保留时间 | 后台清理任务按新规则工作 |
| 历史版本上限 | 之后新产生版本时按新规则裁剪 |
| 在线解压 staging 上限 | 之后新建的在线解压任务按新规则判断 |
| ZIP 压缩包预览开关和限制 | 之后新请求和新建的 archive_preview_generate 任务按新规则 |
| 缩略图源文件大小上限 | 之后新进入缩略图任务的文件按新规则判断 |
| 媒体处理器开关、命令、后缀绑定 | 之后新进入缩略图任务的文件按新规则匹配 |
| 媒体元数据开关、大小上限、处理器绑定 | 之后新进入媒体元数据任务的文件按新规则匹配；已有缓存不会因为改配置自动重扫 |
| 邮件派发、后台任务、周期清理、远程节点健康检测频率 | 之后的后台轮询按新规则 |
| 后台任务车道并发和最大尝试次数 | 之后调度或重试的后台任务按新规则 |
| 分享流播放 session 有效期 | 之后新创建的分享页音频/视频播放 session 按新规则 |
| WebDAV 开关、CORS | 新请求立即按新规则响应 |
关于"自定义配置"
自定义配置 这个分组主要面向自定义前端开发者——它是留给自定义前端开发者的全局变量持久化层。
如果你换了一份自己的前端（替换 ./frontend-override/ 目录），需要持久化一些全站级别的配置（主题、品牌色、自定义入口、第三方接入凭据等），可以用 自定义配置 把它们写进数据库，由后端 API 暴露给前端读写。
命名约定
自定义配置的 key 用 {namespace}.{name} 形式，例如：
my-frontend.thememy-frontend.brand.primary_colormy-frontend.feature.enable_xxx
namespace 用你自定义前端的标识，避免和别人冲突。系统内置配置全部是 source="system"，自定义配置是 source="custom"，两者通过这一字段在后台分开显示。
未使用自定义前端时保持空白
正常使用官方前端的部署，整个 自定义配置 分组保持空白即可——里面的内容不会影响官方前端的任何功能。
如果你只是想找"主题色"、"站点标题"、"Logo"这种东西，请到 站点配置 分组调整。