Yggdrasil 本地开发排障清单（CSRF / 405 / DB / dx 就绪）

沉淀自会话记忆；历史演变多，动手前以当前 .env、compose、README 与 DB 实际配置为准。

CSRF / trusted origin 403

  • 权威 base URL 在数据库的 security_app_base_url；环境变量通常只在首次启动播种，改 env 不覆盖已有 DB 值。
  • 浏览器、测试、Host、Origin、cookie 域必须同源：DB 配 http://localhost:8080 就不能混用 127.0.0.1。
  • 只读 server fn 也是 POST，同样受校验。
  • 不要为了让本地跑通放宽生产 CSRF。
  • 本地 curl 用 --noproxy '*' 排除 SOCKS 代理假故障。

405（跨编译 server fn POST）

Dioxus 0.7 #[server(Fn, "/api")] 的后缀 = xxh64(hash_key + ":" + module_path!(), 0)，hash_key 默认 CARGO_MANIFEST_DIR（编译时绝对路径）。宿主与容器/交叉编译路径不同 → WASM 请求的 hash 与 server 注册的 hash 不一致 → 落到 SSR catch-all 的 GET-only 路由，返回 405 且 allow: GET,HEAD。这是结构性必然，不是缓存或版本漂移。 诊断：容器启动日志 Registering: POST /api/login<数字> vs 浏览器 Network 的 POST /api/login<数字>，比对后缀（精确验证可用 xxh64 手算）。 修法：.cargo/config.toml 的 [env] SERVER_FN_OVERRIDE_KEY 两端统一，然后两端都重建。

数据库连接

  • PostgreSQL 是独立容器 global-postgres（全局 compose 项目），共享 external 网络 global-databases_default。
  • 宿主工具：postgres://issuser@127.0.0.1:5432/yggdrasil；dev 容器必须共享该网络并直连 postgres://issuser@global-postgres:5432/yggdrasil。
  • host.docker.internal 曾同时解析 IPv4/IPv6，容器无 IPv6 路由 → tokio-postgres ENETUNREACH (os error 101)。不要用 extra_hosts 或盲改宿主地址绕过。
  • 容器内 localhost 是它自己。
  • compose 的 environment: 覆盖 env_file:；.env 只供插值，不自动进容器。

dx serve 就绪与卡顿

  • 「Serving your app」banner 早于编译完成，不是就绪信号；验证前查进程、日志与真实 HTTP 响应。
  • 卡在 Waiting for cargo-metadata：查并行 Cargo 进程/缓存锁与 sparse registry 网络，冷 registry volume 可能只需首次刷新。
  • 近零 CPU + 存在 rustup downloads/*.partial：dx 在运行时下载 nightly（cargo +nightly rustc --unit-graph -Z unstable-options）。持久修法是在 Dockerfile.dev 构建期装 nightly + wasm32 target，运行中手装只对该容器有效。
  • dx build/serve 会清 sccache wrapper，避免 RUSTC_WRAPPER 与 Dioxus 的 RUSTC_WORKSPACE_WRAPPER 冲突；普通 cargo 仍可用 sccache。
  • 改 input.css 后必须重新生成 public/style.css（make css）；它是 gitignore 的生成物，dev 容器 watch 的 ignore 列表不包含它。

资源 404

/uploads/xxx.webp 404 先查原文件与 volume：?w= / ?thumb= 不会凭空恢复原图，缺原图只能恢复备份或重新上传并更新引用。

需要管理员会话时

本地开发管理员凭据在仓库 .env（不要打印）。也可直连 sessions 表造短窗口 token：token_hash = sha256_hex(token)，token 为 UUID 字符串；带 Cookie: session=<token> 与同源 Origin 调 /api/<fn><hash>，用完删除该行。

报告纪律

SSR HTML 检查只证明响应与 HTML，不能宣称已验证水合、视觉或交互；Rust、WASM、前端、浏览器验证分开报告，明确阻塞项与未执行项。