故障排查
常见本地问题（认证、端口、签出错误、异常栈）的精准修复方案。
“未找到设备” / 需要身份验证
大多数“身份验证失效”的表现通常由以下原因之一引起：
- 打开了错误的栈 URL（浏览器源冲突）
- 该栈未注入初始身份验证信息（非 main 栈）
- 该栈指向了非预期的代码仓库检出路径
检查：
hstack where
hstack stack info <stack>修复身份验证初始注入：
hstack auth seed
hstack auth seed --force
hstack stack auth <stack> copy-from dev-auth如果该栈已注入身份验证信息，但仍出现身份验证错误或守护进程 401，可以直接修复该栈专属的登录状态：
hstack stack auth <stack> login --force这比手动删除文件更安全。在当前构建版本中，--force 会在重新认证前清除过期的栈专属别名，同时不会影响其他无关凭据。
“该栈使用了错误的代码检出路径”
检查固定的代码仓库：
hstack stack info <stack>
cat ~/.KAIWU/stacks/<stack>/env | rg KAIWU_STACK_REPO_DIR重新指向：
hstack stack wt <stack> -- use dev
# or:
hstack stack wt <stack> -- use pr/123-some-pr端口冲突
如果因固定端口被占用导致 hstack 无法启动：
- 停止该栈：
hstack stack stop ⟦K14⟧ - 或取消固定端口（然后重新运行 start/dev）：
- 使用
hstack stack edit ⟦K15⟧ --interactive，或者 hstack stack audit --fix-ports
- 使用
栈状态异常 / 无法连接服务器
hstack stack doctor <stack>
hstack logs:tail如果使用的是完整服务器模式（KAIWU-server），请检查 Docker：
docker ps如果该栈预期使用运行时快照，请专门检查快照状态：
hstack stack info <stack>
hstack stack info <stack> --json
hstack stack doctor <stack> --json重点排查：
runtime.moderuntime.activeSnapshotIdruntime.snapshotPathruntime.validruntime.errors
常见修复方法：
# rebuild and activate a fresh runtime snapshot
hstack stack build <stack> --activate-runtime
# force the next launch to use the runtime snapshot
hstack stack start <stack> --runtime
# temporarily bypass the runtime snapshot and run from source
hstack stack start <stack> --source如果你只重新构建了单个组件，请注意构建只会更新产物，不会自动更新正在运行的环境：
# new web artifact exists, but the runtime still serves the old UI until activation
hstack stack build <stack> --web
hstack stack runtime <stack> activate --web
# then reload the browser# server/daemon partial activation still requires a restart
hstack stack build <stack> --server
hstack stack runtime <stack> activate --server
hstack stack service <stack> restart“修改了代码但未生效”
在开发模式下，建议至少使用 --restart 运行一次（以便 hstack 接管进程 PID 并安全重启）：
hstack stack dev <stack> -- --restart如果是在栈模式之外运行 hstack dev，请执行：
hstack dev --restart© 乾元执中（南京）科技有限公司 · WUJI-Labs