主题

系统设置 ​

这一篇覆盖 管理 -> 系统设置 里的所有分组

系统设置是管理员在后台直接维护的全站规则。按分组跳到你关心的那一节就行，不必从头读。 大多数改动不需要重启服务，保存后会影响后续新请求、新上传、新发出的邮件。

入口：

text
管理 -> 系统设置

管理员最常改的地方 ​

你想做什么去哪里改
让分享链接、邮件链接、WebDAV 地址、在线预览都指向正确域名站点配置 -> 公开站点地址
改登录页和分享页显示的标题、Logo、favicon站点配置
给 Office 文件加外部预览或 WOPI 打开方式站点配置 -> 预览应用
关闭公开注册用户管理 -> 允许公开注册新用户
改新用户默认配额（创建团队后再核对实际团队配额）存储与保留 -> 新用户默认存储配额
调 Cookie 安全要求、Access / Refresh Token 有效期认证与 Cookie
调激活、改绑、密码重置链接有效期认证与 Cookie
配 SMTP、发测试邮件、改事务邮件模版邮件投递
调回收站、历史版本、团队归档、任务产物保留时间存储与保留
调在线解压临时空间上限存储与保留 -> 在线解压 staging 大小上限
调缩略图大小限制、vips / ffmpeg 处理器存储与保留 -> 媒体处理
关闭 WebDAVWebDAV -> 启用 WebDAV
调邮件派发、后台任务派发、并发、重试、周期清理频率运行与调度
开关审计日志审计日志

当前有哪些分组 ​

  • 站点配置 —— 公开站点地址、标题、Logo、favicon、预览应用
  • 用户管理 —— 公开注册、注册激活、头像、Gravatar
  • 认证与 Cookie —— Cookie 安全规则、Token 有效期、激活/改绑/重置链接有效期
  • 邮件投递 —— SMTP、发件人、测试邮件、邮件模版
  • 网络访问 —— 浏览器跨站访问规则（CORS）
  • 运行与调度 —— 邮件队列、后台任务、周期清理、底层一致性检查、远程节点健康检测、列表上限
  • 存储与保留 —— 回收站、历史版本、默认配额、任务产物、在线解压 staging、媒体处理
  • WebDAV —— 总开关
  • 审计日志 —— 开关和保留时间
  • 自定义配置、其他 —— 高级场景才碰

站点配置 ​

如果站点要对外访问，先把这一组配对。

  • 公开站点地址 填用户真正访问站点的 HTTP(S) 来源，在列表里每个输入框填一个，例如：

    text
    https://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 的推荐顺序

  1. 先填对 公开站点地址
  2. 到 预览应用 里启用已有应用，或通过 WOPI Discovery 导入新应用
  3. 确认外部 Office / WOPI 服务能回连到 公开站点地址 生成的 /api/v1/wopi/...
  4. 如果浏览器跨源调用 AsterDrive API 被拦，再去 网络访问 放行对应来源
  5. 用真实的 docx / xlsx / pptx 试开一次，确认能保存回 AsterDrive

WOPI access token 有效期、WOPI 锁有效期、WOPI discovery 缓存时长 都在这一组里。只有在你已经接了 WOPI 服务、并且确实碰到会话过期或 discovery 更新不及时这类问题时，才需要手动调整。

用户管理 ​

这一组控制账号入口和头像相关行为。

  • 允许公开注册新用户 —— 关闭后登录页只剩已有账号登录和管理员初始化；新增账号只能管理员创建
  • 注册后要求邮件激活 —— 开启后公开注册的普通用户必须先点激活邮件才能登录
  • 头像目录 —— 用户上传头像写到这个本地目录。相对路径解析到服务端 ./data 下
  • 头像上传大小上限 —— 超过的头像文件直接被拒
  • Gravatar 基础地址 —— 访问官方 Gravatar 不稳定时，换成代理或镜像

这一组决定浏览器登录体验和会话安全。

  • 认证 Cookie 仅 HTTPS 发送 —— 正式环境保持开启。只有本地或内网纯 HTTP 试跑时才临时关
  • 访问令牌有效期、刷新令牌有效期 —— 控制登录态维持多久
  • 注册激活链接有效期
  • 邮箱改绑链接有效期
  • 密码重置链接有效期
  • 验证邮件重发冷却时间
  • 密码重置请求冷却时间

正常部署多数时候只需要确认 Cookie 安全要求和链接时效符合你的站点策略。

邮件投递 ​

这一组决定注册激活、密码重置、邮箱改绑邮件能不能发出去。最常改的：

  • SMTP 主机、端口、用户名、密码
  • 发件人地址、发件人名称
  • 是否启用 SMTP 加密
  • 测试邮件
  • 注册激活、密码重置、邮箱改绑邮件模版

准备开放注册前先检查

如果站点要开放注册、找回密码或邮箱改绑，邮件配置和 公开站点地址 要一起检查，别只配一半。

详细指引见 邮件。

网络访问 ​

这一组主要是浏览器跨站访问规则（CORS）。

只在这些场景才需要改：

  • 浏览器页面和 AsterDrive 不在同一个域名下
  • 想让别的站点在浏览器里直接调用 AsterDrive

同站部署一般不用动

大多数"前端页面和接口都在同一个站点里"的部署不需要碰这里。

接外部 WOPI 服务时，最常见的问题不是这里，而是 Office 服务回连不到 公开站点地址 生成的 WOPI URL。只有当浏览器控制台明确报 AsterDrive API 的 CORS 错误时，才需要把对应来源加到这里。

运行与调度 ​

管理员在这里决定后台任务的节奏。默认行为：

任务默认频率
邮件队列扫描每 5 秒
后台任务队列扫描每 5 秒
周期性清理每 1 小时
底层文件一致性检查每 6 小时
系统健康检测（数据库 / 缓存 / 远程节点）每 5 分钟

还能在这里调：

  • 后台任务并发上限
  • 后台任务最大尝试次数
  • 分享下载回滚队列容量
  • 系统健康检测间隔
  • 团队成员列表单页上限
  • 任务列表单页上限

没明显的性能、队列积压或远程节点探测延迟问题，保持默认就够了。
如果你把后台任务并发调大，在线压缩、在线解压和缩略图任务会更容易同时跑起来，CPU、内存和 I/O 压力也会一起上来。

存储与保留 ​

这一组决定"数据留多久"和"新对象默认拿多少空间"。默认规则：

项目默认值
单文件历史版本上限10
回收站保留时长7 天
团队归档保留时长7 天
任务保留时长24 小时
新用户默认存储配额0（不限制）
在线解压 staging 大小上限2 GiB
缩略图源文件大小上限64 MiB

默认配额只影响新对象

  • 界面里这一项的名称就是 新用户默认存储配额
  • 团队创建后的实际配额，建议到 管理 -> 团队 里再核对一次
  • 这个设置只影响之后新创建的对象；已存在的账号或团队不会被自动回写

媒体处理 ​

媒体处理这一块负责缩略图生成，不负责在线预览本身。
它现在在 存储与保留 -> 媒体处理 里有结构化编辑器，不需要手改 JSON。

你可以在那里做这些事：

  • 开关某个处理器
  • 给处理器绑定文件后缀
  • 配置 vips_cli 或 ffmpeg_cli 使用的命令
  • 测试命令是否能被服务端执行
  • 保留 AsterDrive 内置图片处理器作为兜底

默认内置链路覆盖常见图片格式。
如果你想给 HEIC、AVIF、PDF 封面或视频缩略图扩展能力，可以接 vips 或 ffmpeg，但前提是这些命令真的装在服务端环境里。

先别把内置处理器关掉

除非你已经确认 vips / ffmpeg 的命令路径、权限和后缀绑定都没问题，否则保留内置处理器当兜底更省心。

WebDAV ​

这里目前最重要的就是：

  • 启用 WebDAV

关闭后桌面客户端会立刻无法继续通过 WebDAV 访问文件。

不在这里改路径前缀

如果你只是想改 WebDAV 路径前缀或 WebDAV 上传体积硬上限，那不在这一页，而是在 config.toml 的 [webdav] 里改，改完要重启。

审计日志 ​

这一组决定后台和关键操作是否留下记录。

  • 启用审计日志
  • 审计日志保留时长

别轻易关掉

想之后还能追查"谁删了文件、谁创建了分享、谁改了团队成员"，就别关它。

修改后什么时候生效 ​

改动生效时机
站点地址、标题、Logo、favicon刷新页面后按新值显示
预览应用 / 在线 Office 相关之后新打开的预览按新规则
WOPI access token / 锁 / discovery 缓存之后新开的 WOPI 会话按新规则
公开注册、注册激活、邮件模版之后新进入登录流程、新发出的邮件按新规则
Cookie 安全、Token 有效期之后新登录、刷新、分享密码验证按新规则
头像目录、头像上限之后新上传头像按新规则
默认配额只影响之后新创建的对象
回收站、团队归档、任务产物、审计日志保留时间后台清理任务按新规则工作
历史版本上限之后新产生版本时按新规则裁剪
在线解压 staging 上限之后新建的在线解压任务按新规则判断
缩略图源文件大小上限之后新进入缩略图任务的文件按新规则判断
媒体处理器开关、命令、后缀绑定之后新进入缩略图任务的文件按新规则匹配
邮件派发、后台任务、周期清理、远程节点健康检测频率之后的后台轮询按新规则
后台任务并发和最大尝试次数之后调度或重试的后台任务按新规则
WebDAV 开关、CORS新请求立即按新规则响应

关于"自定义配置" ​

自定义配置 这个分组不是给日常管理员拨弄的——它是留给自定义前端开发者的全局变量持久化层。

如果你换了一份自己的前端（替换 ./frontend-override/ 目录），需要持久化一些全站级别的配置（主题、品牌色、自定义入口、第三方接入凭据等），可以用 自定义配置 把它们写进数据库，由后端 API 暴露给前端读写。

命名约定

自定义配置的 key 用 {namespace}.{name} 形式，例如：

  • my-frontend.theme
  • my-frontend.brand.primary_color
  • my-frontend.feature.enable_xxx

namespace 用你自定义前端的标识，避免和别人冲突。系统内置配置全部是 source="system"，自定义配置是 source="custom"，两者通过这一字段在后台分开显示。

不写自定义前端就别动

正常使用官方前端的部署，整个 自定义配置 分组保持空白即可——里面的内容不会影响官方前端的任何功能。

如果你只是想找"主题色"、"站点标题"、"Logo"这种东西，去 站点配置 分组，不在这里。

基于 MIT 许可证发布

Copyright © 2026 AptS:1547