本地调试（magic-stack）

magic-stack 是一个工具无关的全局技能：用于跨项目的本地 Docker 调试 —— adopt 已有容器、共享 infra（postgres/redis/kafka 等）、模板化的热更新应用容器、 Markdown 预览。安装到 ~/.magic-stack/。

本机启动 / 调试 / 联调任何服务都应走 magic-stack，而非裸 docker compose / docker run。

magic-stack 的配套 GUI 是开发工作台（负责登录 + 设备注册、写本机契约文件）； 本页只讲 CLI 的安装与命令。

安装

magic-stack 随 magic-skills 合集一行装到位，安装后 magic-stack 命令全局可用。 完整步骤（前置依赖、内 / 外网命令、桌面端、升级、卸载）见 安装整套技能。

全局共享基础设施

magic-stack 维护一套共享 infra，端口统一 17XXX 前缀（与原服务默认端口解耦）：

服务	宿主端口
workbench（工作台）	17070
postgres	17432
redis	17379
kafka	17092

更多端口见 magic-stack 全局 infra 配置。

常用子命令

命令	作用
magic-stack init [path]	注册项目，生成 .magic-stack/ 配置
magic-stack up [project] [stack...]	启动 stack
magic-stack down [project] [stack...]	停止 stack
magic-stack restart <project> <stack> [--rebuild]	重启单个 stack
magic-stack status [project]	查看状态总览
magic-stack logs <project> <stack> [service] [--follow] [--tail=N]	跟服务运行日志
magic-stack hot <project> <stack>	查热更新规则（改什么需要 restart）
magic-stack adopt --all	收编现有 infra 容器
magic-stack sync [project]	引擎升级后重渲染项目引擎产物

读日志是只读操作，不受「禁裸 docker」约束。容器名规则：<项目slug小写>-<stack>[-<service>]。

典型流程

# 1. 注册项目
magic-stack init /path/to/myproject

# 2. 启动
magic-stack up myproject backend

# 3. 跟日志
magic-stack logs myproject backend --follow --tail=100

# 4. 停止
magic-stack down myproject backend

查看日志（排错）

# magic-stack 跟日志
magic-stack logs <project> <stack> [service] --follow --tail=200

# 直接过滤容器报错（DEBUG 刷屏时）
docker logs --since 30m <容器名> 2>&1 | grep -iE "ERROR|Exception|Caused by" | tail -40

本机授权门禁

magic-stack 同时是设备授权内核的本机客户端。它读取 ~/.magic-stack/auth.json （由开发工作台登录后写入）与 device.id，凭设备 token 放行受控命令。

放行逻辑

• token 有效 → 放行。
• token 失效 / 设备被吊销 / 账号被停用 → 拒绝，提示重新登录。

本机契约文件

文件	内容
~/.magic-stack/device.id	本机安装 UUID（不含尾换行）
~/.magic-stack/auth.json	登录态：platform_url、user、device_id、device_name、access_token、access_exp（秒）、refresh_token、last_online（秒）

这两个文件由开发工作台在登录 + 设备注册后写入；magic-stack CLI 读取它们校验设备身份。 授权内核的服务端契约见 开发者平台 / 设备授权内核。