# 升级 / 故障排查

## 升级（规格 §36）

1. 备份 AList data/config。
2. 读 release notes（github.com/AlistGo/alist/releases）。
3. 固定新版本 tag（如 `v3.64.0`），改 `docker-compose.yml` 的 `image:`。
4. Portainer → Recreate / `docker compose pull && up -d`。
5. 跑 `scripts/healthcheck.sh`。
6. 跑 n8n Full Reconciliation（WF4）。
7. 验证 sample customer 权限。
8. 异常则回滚 tag + 还原备份。

## 故障排查

| 症状 | 排查 |
|---|---|
| container unhealthy | `docker logs alist-serve-resource`；确认 `/ping` 返回 200 |
| 挂载 MISS | 确认 NAS 目录名与 compose volumes 一致 |
| 客户看不到路径 | 检查 role `permission_scopes`、user `permission` bit 14、storage mount path |
| 客户能写文件 | 检查 user `permission` bitmask 是否误设 bit 3–7；确认挂载 `:ro` |
| n8n 连不上 alist | 确认同 `bridge_hoelee` 网络、host 名 `alist-serve-resource` |
| 到期未撤销 | 确认 WF3 每 5 min 触发；查 NocoDB `sync_status` |

详细排查步骤 Phase 10 补全。