alist-serve-resource/docs/PROJECT_STATE.md

Project State (Handoff) — 2026-08-25

交接文档：压缩/新会话后按此续做。入口顺序：AGENTS.md → 本文件 → SECRETS.md(凭据)。 本文件只记「状态与下一步」；API 怪癖/坑的唯一权威 = Hermes skill alist-serve-resource + docs/API_INTEGRATION.md。

凭据

全部集中在根目录 SECRETS.md（唯一凭据文件；把项目给别人 = 删它即可）。 表 ID / workflow ID 不是机密，见 docs/DATABASE_SCHEMA.md 与下文。

系统现状（2026-08-25 实测）

• 容器全绿：alist-serve-resource(healthy) · nocodb · n8n · nginx-limit-alist · traefik-update-alist（08-25 全部 redeploy）
• 公网上线 ✅：https://drive.digikedai.com 经 CF Tunnel 全链路实测通 （/ping pong、/ 与 /login 均 200 AList SPA、/@manage 403 防护有效）
• W1–W4 四个 workflow 激活正常（postgres 复核 activeVersionId 全对齐；08-25 PUT 更新后仍对齐）
• 端到端实测通过 ✅（08-25）：真实业务事件全链路——建 Customer→W1 自动开通+写回； 建 CP→W2 自动算 scopes（/Class/Forex）；AList 真实登录/范围内 200/范围外 403； CP 到期→W3 sweep 收权；Customer suspended→W1 禁用（客户 token 全 API 401）； active 恢复→重启用重算；人为漂移→W4 dryRun 只报告不写入 / 正式跑修复且幂等。
• 08-25 三处基础设施修复：① AList /user/update 必须带 username（否则 400 静默不禁用） → w1/w3-body.js 已修并部署；② NocoDB 两 hook 改指 http://n8n:5678（原 auto.hoelee.com 走旧公网链路，VPS 卡顿时事件静默丢失），W2 hook 路径 alist-cp-sync→alist-customerproduct-sync （原来一直 404）；③ n8n API key 已入档 SECRETS.md。
• n8n「执行消失」已结案：容器 env EXECUTIONS_DATA_SAVE_ON_SUCCESS=none，成功执行不落库是配置使然，管道健康（详见下方结案记录）
• NocoDB 数据：Products 176 / Resources 171（商品目录健在）；Customers/CustomerProducts 测试数据已清空（残留 1 行上个会话的 e2e_test_01 待用户处置）；AList 仅 guest/hoelee(+e2e_test_01 残留)

已完成 ✅（细节见各 DESIGN 文档与 git log）

1. Phase 1 AList stock v3.63.0 :5244（bridge_hoelee，4 只读挂载；旧 alist 已下线，compose 内注释保留）
2. Phase 2 NocoDB base AlistAccess(p3lzkresswyowqg) 8 表（7 业务 + ReconcileLogs）；脚本 scripts/create_nocodb_schema.py / add_reconcilelogs_table.py
3. W1 客户开通 + 5 状态 lifecycle（pending/active/suspended/expired/deleted）— 实测跑通；old/new 字段比对 loop guard + sync_required 强制重算 + writeBack 值比对守卫（test_w1_lifecycle.js 10 场景全过）
4. W2 CustomerProduct 权限同步（调共享算法）— 实测跑通
5. W3 每 5 分钟 expiry sweep（W3_DRY_RUN / ALIST_AUTO_DISABLE_ON_EXPIRE 开关）— 实测跑通
6. 共享库 n8n/shared/effective-grants.js 单一事实源，构建期内联（gen_w*.js），三 workflow 零复制算法；union 语义：CP 派生 ∪ AccessGrants，同 path 取 MAX(expires_at)，expiry 边界 <= today
7. W4 每日 03:00 全量对账 + ReconcileLogs 审计 — 本地 + 直连生产实测通过（dry-run→repair→复跑幂等；34 项 mock 测试过）；单向同步 NocoDB=SOT，密码不随 repair 推送（方案 C）
8. 文档体系：ARCHITECTURE / PERMISSIONS / ADMIN_GUIDE / DATABASE_SCHEMA / N8N_WORKFLOWS 等；git 已推 Gitea
9. 公网链路切换（08-25）：DSM 文件统一收进 /volume1/docker/alist-digikedai/（容器名全部未动——n8n ALIST_URL 硬依赖）；CF Tunnel drive.digikedai.com 回源 http://172.16.0.1:5246；traefik 删除 /login→n8n 劫持路由（曾致登录页挂起）；nginx 移除 drive 域不限速白名单（现吃默认 1.5MB/s + limit_conn 10/IP）。完整记录 = DSM /volume1/docker/alist-digikedai/alist-serve-resource/NETWORK_ARCHITECTURE.md

🔴 下一步（按序）

1. 补 n8n env 并 rebuild（Portainer stack 144，改 env 必须 rebuild）：NOCODB_TABLE_RECONCILELOGS=mktsb7le6fqr2u1 + NOCODB_FK_RECONCILELOG_CUSTOMER=nc_jitu___Customers_id（W4 审计落库当前被跳过）；顺手加 TZ=Asia/Kuala_Lumpur 修 UTC 时区
2. 决策：auto.hoelee.com 是否退役/迁移——n8n 公网访问现在只剩 UI 用途；hook 已容器化。若保留，建议迁到 CF Tunnel 新链路；若退役，同步删 VPS DNS + DSM 反代条目
3. 清理上个会话残留：NocoDB Customer Id=8 e2e_test_01 + AList user 17 / role customer-e2e_test_01
4. 公网限速实测：经 CF 后确认 nginx 限速按访客真实 IP 计（若 key 变 docker 内网 IP 全员共享一桶 → 调 traefik ipStrategy depth / nginx XFF）
5. 旧链路退役清理：旧 alist 数据目录、DSM 反代 access.hoelee.com 条目、VPS DNS、compose 注释块择机删
6. AList site_url 设为 https://drive.digikedai.com（分享链接需要）
7. 密码保持方案 C（客户可自改 AList 密码 → NocoDB plaintext 失真；不强制回写）
8. W2 不写 CP bookkeeping（sync_status/last_sync 永不更新）——现状可用；若未来有逻辑依赖这些字段再补写回节点

结案记录

• CF Tunnel drive.digikedai.com 打不通（08-25 发现 → 当日结案）
  • 现象：公网 TCP/TLS 能建立但 HTTP 层零响应超时；DSM 内部链路对任意 Host 头都正常 → 不是 hostname 检查
  • 根因：cloudflared 在 bridge_hoelee 网络，容器→宿主机自身 LAN IP (192.168.1.1:5246) 被 DSM 防火墙 hairpin 丢弃（日志 dial tcp ... i/o timeout）；同隧道其他站点源是别的机器所以没事
  • 修复：CF Dashboard 回源改 http://172.16.0.1:5246（docker0 网关=宿主机），实测公网 pong。备选：容器 DNS 名 nginx-limit-alist:5246
  • 同场加映：traefik rtr-alist-login 把 GET /login 劫持到 n8n(:5678)，n8n 无此路由 → 登录页挂起 499。已删路由 + 孤儿 middleware mw-webhook-user-rewrite（备份 dynamic.yml.bak-20260825）
• n8n 执行管道停摆（08-23 报告 → 08-24 结案，误报）
  • 现象：webhook 全 200 但 executions 表零记录、schedule 无痕迹
  • 根因：EXECUTIONS_DATA_SAVE_ON_SUCCESS=none → 成功执行从不落库，只有 error 会记（期间唯一入库记录恰是一条无关备份 workflow 的 error，完全吻合）
  • 时间线：最后 success 记录 08-22 23:00:51Z ≈ 容器重建（08-23 01:21Z Started）前后；激活错位（activeVersionId）已在重建后修复
  • 若要恢复可见性：env 改 all / all-with-logs（EXECUTIONS_DATA_PRUNE 已配，不会无限涨）
  • 另注：DSM IP 已漂移为 192.168.137.2；Windows 直连内网端口（AList 5244 / NocoDB 10380 / n8n 5678）均通

⚠️ 坑速览（一行版；详情看 skill alist-serve-resource Pitfalls + API_INTEGRATION.md）

• AList：空 role 建用户必 400（先建 role）｜base_path 必须 / 否则双重前缀全 403｜delete 用 ?id=｜裸 token 无 Bearer
• NocoDB：link 查询必须 (link.Id,eq,N)｜写 bt 链接要写 FK 列 nc_jitu___*_id｜删行 DELETE+body｜v1 列端点已废｜SingleSelect 先建空列再 PATCH
• n8n：Code 节点 $env 可用、HTTP 表达式不行（Load Env 模式）｜API 导入节点 id 必须 UUID 且顶层无 pinData｜webhook 节点缺 webhookId 则生产 URL 不注册｜激活真标志=DB 的 activeVersionId｜执行消失假象=SAVE_ON_SUCCESS
• 环境：DSM IP 会漂移（连不上先探测，08-25 起在 192.168.137.2）｜DSM sshd 无 SFTP（POST body 用 stdin pipe 传）｜容器→宿主 LAN IP 被 hairpin 丢包，回宿主机服务用 172.16.0.1 或容器 DNS 名

Status 语义已定稿：pending/active/suspended/expired/deleted，account-level 整户开关， 不进 permission calc。详见 docs/ARCHITECTURE.md、docs/PERMISSIONS.md、docs/DATABASE_SCHEMA.md。

项目结构

alist-serve-resource/
├── AGENTS.md            ← 🤖 AI 会话入口（任务路由 + 铁律，开工先读）
├── SECRETS.md           ← 🔑 唯一凭据文件（外发 = 删除此文件）
├── docker-compose.yml / .env.example / .gitignore
├── n8n/
│   ├── W1..W4-*.json (生成物，勿手编) · w1..w4-body.js (运行时逻辑源头)
│   ├── shared/effective-grants.js (算法单一事实源) · gen_w1..w4.js + inline_shared.js (构建)
│   ├── test_*.js · SETUP.md · W2/W3/W4-DESIGN.md
├── scripts/  create_nocodb_schema.py · add_reconcilelogs_table.py · live_dry_run_w4.js · healthcheck.sh
└── docs/  API_INTEGRATION · ARCHITECTURE · PERMISSIONS · ADMIN_GUIDE · DATABASE_SCHEMA ·
          N8N_WORKFLOWS · PROJECT_STATE(本文件) · INSTALL · CONFIGURATION · SECURITY ·
          BACKUP_RESTORE · UPGRADE · TROUBLESHOOTING · W4-DESIGN

待确认的设计点

1. AccessGrants 物化 —— 定案：不物化（手工人为授权入口，n8n 永不写）
2. 密码失真 —— 定案：方案 C（不强制回写；W4 repair 不推密码，仅 provision 新建时用）
3. 对账/到期只靠 n8n 定时扫描（AList 无 expiry 概念）—— 已确认