alist-serve-resource/docs/INSTALL.md

安装文档（Phase 1：AList stock 部署）

目标：在 DSM 上跑起全新的 stock AList，与旧 alist 并行，验证后再切换域名。

0. 前置条件（你需独立操作）

这些是你在 DSM / Portainer 上手动完成的部分，agent 无法代劳：

1. 确认 NAS 目录存在且就绪：

   • /volume1/Class、/volume1/Book、/volume1/Comic、/volume1/Template
   • 若目录名/路径不同，改 docker-compose.yml 的 volumes。

2. 创建 AList 数据目录（DSM File Station 或 SSH）：

   /volume1/docker/alist-serve-resource/data
   /volume1/docker/alist-serve-resource/config
   /volume1/docker/alist-serve-resource/storage
   

3. 确认外部网络 bridge_hoelee 存在：

   • 该网络由 n8n/nocodb 等其他 compose 创建（external: true）。
   • 若不存在，在 DSM 上建：docker network create bridge_hoelee（或 Portainer → Networks → Add）。

4. 准备 secrets：

   • 复制 .env.example → .env，填入真实 JWT_SECRET、ALIST_ADMIN_PASSWORD 等。
   • 生成 JWT secret：openssl rand -base64 32

1. 部署（Portainer）

在 Portainer → Stacks → Add Stack：

• Name: alist-serve-resource
• 方式：上传 docker-compose.yml + 配置环境变量（或把 .env 内容填入 Environment variables 区）。
• 网络 bridge_hoelee 是 external，Portainer 会复用现有网络，不会新建。

Portainer 与 env_file：Portainer Stack 使用内置 Environment variables 区而非 .env 文件。 把 .env 里的键值对逐条填进 Portainer 的 Environment variables，或改用 Compose 里的 ${VAR} 语法（Portainer 也支持 env_file，可上传 .env 作为 env_file）。

部署后验证：

docker ps | grep alist-serve-resource
docker logs alist-serve-resource

2. 首次初始化 AList admin

1. 访问 http://<DSM-IP>:5247。
2. 首次进入会引导设置 admin 账号密码（或 AList 会打印初始 admin 密码到日志： grep -i admin docker logs alist-serve-resource）。
3. 登录后台，确认版本 v3.63.0。

3. 建立 Local Storage

AList 后台 → 存储 → 添加 → 驱动选「本地存储 / Local」：

挂载路径: /Class      →  根文件夹路径: /mnt/Class
挂载路径: /Book       →  根文件夹路径: /mnt/Book
挂载路径: /Comic      →  根文件夹路径: /mnt/Comic
挂载路径: /Template   →  根文件夹路径: /mnt/Template

客户看到的逻辑路径是 /Class/...，实际 host 是 /volume1/Class/...（规格 §31）。 客户永远看不到 /volume1 或 /mnt。

4. 验证健康检查

docker inspect --format '{{.State.Health.Status}}' alist-serve-resource
# 应输出 healthy

5. 切换域名（后期，新旧并行验证通过后再做）

1. 旧 alist（nginx-limit-alist/traefik-update-alist/alist）保持运行。
2. DSM nginx 将 access.hoelee.com 新指到 http://<DSM-IP>:5247。
3. 验证客户能正常登录/浏览/下载。
4. 确认无误后，停掉旧 alist 三个 container（先 docker stop，观察，再 docker rm）。

6. 后续 Phase

• Phase 2：NocoDB schema（docs/DATABASE_SCHEMA.md）
• Phase 3：n8n + AList API 连接（docs/N8N_WORKFLOWS.md）
• Phase 4–10：客户建档、权限同步、到期同步、审计、监控、备份、文档