主题

故障排查 ​

这一篇覆盖部署后最常见的几类异常：服务起不来、上传下载失败、分享访问异常、WebDAV 连不上、Office / WOPI 加载白屏、后台任务不跑、升级后异常。
按你看到的现象往下找对应章节即可，不必通读。

如果你的现象不在本篇范围内（比如功能性 bug、数据问题），先跑一次 aster_drive doctor，再看 还是没解决。

排查前先做两件事：

  1. 看一眼 /health 和 /health/ready 的返回，能直接告诉你是 DB 不通还是存储后端没起来
  2. 看一眼最近的日志；AsterDrive 的错误码会带 error_code，比对 错误码处理 比看英文报错快

服务起不来 ​

启动直接退出，没有日志 ​

通常是配置加载阶段就报错了，日志还没初始化。

按这个顺序看：

  1. 当前工作目录是不是你以为的目录；data/config.toml 是按工作目录算的
  2. data/config.toml 有没有写权限；首次启动需要写入
  3. 环境变量 ASTER__ 前缀里有没有打错的 key（拼写错了不会被忽略，会让加载失败）
  4. 数据库 URL 是否能解析；SQLite 路径错了也算这一类

/health 200 但 /health/ready 503 ​

/health 只看进程活着，/health/ready 会真的 ping 数据库和默认存储策略。

按 503 返回里的 error_code 区分：

  • database_error：DB 连不上；先看连接字符串、网络、用户名密码
  • 存储相关错误码：默认存储策略起不来；如果是 S3，看 endpoint、credentials、bucket 是否存在；如果是 local，看路径权限

改完配置不生效 ​

分两种：

  • data/config.toml 改完要重启进程才生效
  • 管理 -> 系统设置 里大多数运行时配置不需要重启；页面标了“需要重启”的项，按页面提示重启
  • 访问限流不在系统设置里，它是 config.toml 的 [rate_limit]，改完要重启

如果你改了运行时配置发现不动，先看一下后台对应那一项的描述里有没有"重启后生效"字样。

上传失败 ​

直传小文件失败，分块大文件成功 ​

直传走 web::Bytes 一次性收完整 body，body 上限受 actix 默认限制和反向代理同时影响。

按这个顺序看：

  1. 反向代理（nginx / caddy / traefik）的 client_max_body_size 或等价配置
  2. WAF / CDN 是否拦了
  3. 网络中间设备是否有自己的 body 上限

大文件走 chunked 上传，每个 chunk 默认 5 MiB，所以你不容易在 chunk 上踩 body limit。

分块上传走到一半卡住 ​

先看是哪一阶段卡：

  • 卡在某个 chunk：通常是网络断了；前端会自己重试，看浏览器开发者工具里那个请求的状态
  • 全部 chunk 上传完但 complete 不返回：服务端在合并和算 SHA256，文件大就慢；不要立即重试 complete，会触发去重路径但浪费一次合并

提示 upload_session_expired ​

大多数可恢复上传会话是 24 小时；S3 / 远程节点的单次 Presigned 直传短会话通常是 1 小时。以前端恢复列表或服务端返回的 expires_at 为准。

如果你打算上传超大文件且预计会跨天，建议在前端上传前确认一下网速。会话过期后没有自动续期，必须重新发起。

提示 chunk_upload_failed ​

最常见的是磁盘满了。

按这个顺序看：

  1. data/.uploads 所在分区可用空间
  2. 该用户配额是否已经用完
  3. 默认策略 / 用户绑定的策略组是否被禁用

提示 upload_assembling ​

后端正在合并 chunk，不是错误。等几秒重试 complete 就行；如果反复出现且持续 1 分钟以上，看一下 data/.uploads 临时目录有没有异常。

下载与预览 ​

下载到一半断流 ​

下载走流式 + Range 支持，断了重连即可续传。

如果反复在同一位置断：

  • 反向代理的 proxy_read_timeout 或等价配置；大文件下载需要长 read timeout
  • 客户端到服务的链路是否有 idle timeout（CDN、Cloudflare Tunnel 之类）

预览打不开 / Office 文件无法打开 ​

按预览类型分：

  • 图片 / 视频 / 代码：浏览器原生预览，看浏览器控制台是否有 CSP / MIME 报错
  • Office 文件：取决于你接的预览方式
    • 如果走外部预览器，先在 管理 -> 系统设置 -> 站点配置 -> 预览应用 里看绑定是否正确
    • 如果走 WOPI（Collabora / OnlyOffice），需要确认 WOPI 服务能反向访问到 AsterDrive 的公开站点来源（Origin）

WOPI 接入细节见 文件编辑。

分享访问 ​

分享链接 404 ​

可能性按概率排序：

  1. token 拼错或被截断（特别是从微信 / 企业 IM 复制时）
  2. 分享已过期（超过 expires_at）
  3. 分享已删除
  4. 分享次数已达 max_downloads 上限

分享要密码但密码对了还是失败 ​

先分清是"还没验证"还是"验证失败"：

  • share_password_required：当前请求没有有效的分享密码验证 cookie，通常是还没验证、cookie 丢了或验证已过期
  • auth_failed：提交密码时密码不对
  • share_expired / share_not_found：是上一节的情况，不是密码问题

服务端有 1 小时密码验证缓存，改完密码后对方在 1 小时内仍然可能用旧密码访问。这是有意设计，不是 bug。

WebDAV ​

客户端连不上 ​

按这个顺序看：

  1. 系统设置里 WebDAV 总开关是不是关的；关了会直接返回 503
  2. 反向代理是否放行 WebDAV 方法（PROPFIND / MKCOL / MOVE / COPY / LOCK / UNLOCK）；nginx 默认只放行 GET/POST/HEAD
  3. 反向代理是否放行 Depth / Destination / Overwrite / If 等请求头
  4. URL 是否包含正确的 /webdav 前缀

反代配置示例见 反向代理部署。

能连上但所有操作都 401 ​

WebDAV 走自己的账号系统，不是普通登录账号。在个人空间左侧 WebDAV 页面里创建专用账号。

普通登录的 JWT 也可以用 Bearer 鉴权，但大多数 WebDAV 客户端不支持自定义 header，所以用专用账号最省事。

能列目录但写入失败 ​

看错误码：

  • resource_locked：文件或文件夹被 WebDAV LOCK 占住；通常是另一个客户端没释放，或上一次客户端崩溃没 UNLOCK，等锁过期或在管理后台手动解锁
  • precondition_failed：客户端发了 If-Match / If-None-Match 但条件不满足；多见于多端同时改同一个文件
  • 配额相关：用户配额已满

Office / WOPI ​

Collabora / OnlyOffice 加载白屏 ​

最常见的是 WOPI 服务无法回连 AsterDrive。

WOPI 协议要求预览服务从 AsterDrive 拉文件内容，所以预览服务那一侧必须能访问到你配置的公开站点来源（Origin）。生成 WOPI 地址时，AsterDrive 会先按当前请求 Origin（scheme + host[:port]）精确匹配；命中用该来源，未命中时回退第一项。确保这个最终选中的来源能被 WOPI 服务访问：

  • 预览服务和 AsterDrive 都在 Docker 里：用 Docker network，公开站点来源用对方能解析的域名
  • 预览服务在外网：公开站点来源必须是公网可达的 HTTPS
  • 预览服务在内网：公开站点来源用内网域名 + 内网证书

提示 token 失败 / 401 ​

WOPI access_token 是短期的；如果客户端打开很久后才操作，token 可能过期。刷新页面会重新申请。

如果是重复出现：

  • 检查 AsterDrive 时钟是否正确；WOPI proof-key 校验有 ±20 分钟时间窗
  • 检查 WOPI 服务自己的时钟

后台任务 ​

邮件发不出去 ​

先去 管理 -> 系统设置 -> 邮件投递 发一封测试邮件，再看服务端日志里 mail outbox / SMTP 相关报错。

按现象分：

  • 全部失败：SMTP 配置有问题；用 管理 -> 系统设置 -> 邮件投递 里的"发送测试邮件"先验证连通性
  • 部分失败：可能是收件人地址被对方域阻止；看具体投递日志
  • 状态像是一直不动：先确认服务进程还在跑；如果想看系统调度有没有继续工作，可以到 管理 -> 任务 看最近的系统任务记录里有没有持续失败的 Mail outbox dispatch

缩略图一直没出来 ​

缩略图是 worker 异步生成的；上传后通常几秒到几十秒出来。

如果一直没有：

  1. 文件类型是否在支持列表里（图片大部分支持，视频部分支持）
  2. 文件大小是否超过缩略图生成上限
  3. 管理 -> 任务 里最近有没有持续失败的缩略图或系统任务记录

回收站项目过期没清 ​

清理任务每小时跑一次，不是即时。如果你确认设置是 30 天，刚到 30 天的不会立刻消失。

如果一天后还在：

  • 管理 -> 系统设置 -> 存储与保留 里的回收站保留天数是否真改了
  • 管理 -> 任务 里最近有没有持续失败的 Trash cleanup 系统任务，或者直接看服务端日志

升级后异常 ​

升级后启动报数据库相关错误 ​

通常是数据库迁移没跑完。

二进制和 Docker 镜像都会在启动时自动跑 migration，但如果数据库账号没有 DDL 权限，会失败。

按这个顺序看：

  1. 数据库账号是否有 CREATE / ALTER 权限
  2. 启动日志里 migration 阶段的具体报错
  3. 如果是从很旧的版本升过来，可以先用 aster_drive database-migrate 单独跑迁移，看更详细的报错

升级后某些功能"消失"了 ​

不是消失，是位置改了。先看 更新日志 对应版本段。

如果你用的是 alpha 版本之间的升级，建议升级前先备份。详见 备份与恢复。

还是没解决 ​

按这个顺序提交问题：

  1. 跑一次 aster_drive doctor，把输出贴上
  2. 把 /health/ready 的完整 JSON 贴上
  3. 把现象出现前后的日志（最少前后各 50 行）贴上
  4. 在 GitHub Issues 开 issue

不要删 error_code 字段。error_code 是定位问题最快的线索。

基于 MIT 许可证发布

Copyright © 2026 AptS:1547