Nexau Deploy And Debug

NAC 部署上线与排障

写给谁：在 NAC 平台上运行 agent 的使用者。你有平台账号、Web 控制台、nac 命令行和 公开 API；没有源代码、没有集群权限。本 skill 里的每条判据都能用这三样自己验证。

和另一个 skill 的分工：制品怎么写（agent.yaml / 工具 / Skill / MCP / 依赖 / 对象存储） 一律去 nexau-artifact-builder。本 skill 从「制品已经写完了」开始接手。

概念不在这里：版本 = 不可变快照、环境 = 指针、蓝绿切换、平台管什么你管什么 —— 这些看使用指南正文；本 skill 只讲怎么做和判据是什么。

0. 怎么用本 skill

1. 先确认你有哪把钥匙（从这里开始，不要跳）

平台有两个面，凭据不通用。这条不先弄清楚，后面所有排障命令都会以看不懂的 401/403 收场。

nac auth whoami          # 自检：当前是谁、连的哪个平台、项目是哪个
nac auth login           # 交互粘贴 PAT
nac auth login --token nacp_xxx      # 非交互（CI）
nac tokens list / create <name> / delete <id>

三条硬边界（每条都有专属报错，见 references/error-codes.md）：

1. AK/SK 打管理面直接 403，message 原文 AK/SK credentials are valid only on the data plane (/agent-api/*)…。 ⇒ 只拿到 AK/SK、没有控制台账号的人，用不了 nac deploy / logs / traces / versions， 排障只能靠对话面证据（§3 里标了「AK/SK 可用」的那几项）+ §5 报障清单。
2. PAT 打对话面忘带 X-Project-Id 是 400 不是 401，message Missing X-Project-Id header (required when using user credentials)。 别在 401 分支里找它。
3. PAT 和 AK/SK 读同一个 session 的可见范围不一样：AK/SK 只校验「session 属于本项目」， PAT 还额外校验「发起人是我」（比对建 session 时的 distinct_id）⇒ 同一个 session AK/SK 读得到、PAT 读 404 session not found。这不是 session 丢了，见 §4。

给 CLI 临时换凭据：nac --token "ak_xxx:sk_xxx" smoke staging（--token 同时接受 PAT 和 ak:sk）。

1.1 PAT 能做多少事 —— 三条先记住

1. PAT 就是你本人，没有权限范围。 创建时只能设名字和有效期（7d/30d/90d/365d/永不过期）， 做不出「只读 PAT」或「只管一个项目的 PAT」。⇒ 一把 PAT 泄露 = 整个账号泄露： 给 CI 的令牌设短有效期、一个用途一把、定期用 nac tokens list 清掉不用的。
2. 非管理员也能创建 PAT，这是正常的 —— 它不是提权手段，跟管理员身份无关。 反过来，管理员身份挂在账号上不在令牌上：同一把 PAT，账号被授予/取消管理员之后能做的事会立刻跟着变。
3. 常规开发部署一件管理员的事都不需要。 24 个顶层命令没有一个要管理员权限。 ⭐ 尤其是：你自己创建的项目，你就是 owner —— 读写治理全部直接放行， 用自己的 PAT 部署到自己项目的环境是完全正常的日常操作，不需要任何额外授权。 「够不够权限」这个问题只在别人的项目、你被拉进去协作时才需要问。

判据（够用了）：路径以 /api/admin/ 开头 = 必须管理员，其余都不是。 只有 nac api 这个逃生舱能打到它们，其余 23 个命令都碰不到。

完整的「命令 → 需要哪一档」对照表、以及三种 403 怎么区分，见 references/pat-permissions.md。

2. 部署与版本管理

2.1 命令动词（别照直觉猜，猜错的命令不一定报错）

平台没有 nac promote / nac switch / nac remove / nac rollback / nac chat status 这些顶层命令。 ⚠️ 而且**「把某个环境的版本直接发到另一个环境」这个能力本身就不存在** —— 别去找它的命令形式，见下表的注。 写错的后果可能是静默的：nac chat status 会被解析成「对一个叫 status 的环境发起对话」。 权威清单永远是 nac --help（当前 24 个顶层命令，逐条见 references/cli-reference.md）。

⚠️⚠️ 上面这些「拿已有版本去部署」的写法都只在本环境内成立。 平台没有跨环境通路：要把预发验过的东西发到生产，必须把制品重新上传部署一次 （nac deploy production），在生产环境下产生一条新的 Version。 | 启用 / 停用版本 | nac versions activate <vid> / deactivate <vid>（已绑环境时要 --confirm） | | 无损重启当前版本（不换版本、不重新打包） | nac versions redeploy <vid> | | 看 / 改某版本的副本上下限 | nac versions scaling <vid> / nac versions scaling <vid> --min 1 --max 5 | | 直接把副本数拨到 N | nac versions scale <vid> <N> | | 看环境与当前指向 | nac status --json ⚠️、nac environments list、nac environments releases <env> | | 建临时环境 / 续期 / 删 | nac environments create --name lab --ttl 1h / extend <env> --ttl 2h / delete <env> | | 运行日志 / 版本启动日志 | nac logs <env> / nac versions logs <version_id> | | trace | nac traces --last 1h / nac trace <id> / nac trace <id> --export -o t.json | | 冒烟 / 用例套件 / 压测 | nac smoke <env> / nac test <env> / nac bench <env> | | 打任何后台接口（逃生舱） | nac api GET/PUT/POST/DELETE <path> --body '<json>' |

⚠️ nac status 的表格输出只有 Environment / Type / Expires At / Created 四列，看不到「指向哪个版本」 —— 要看部署必须 --json 读 current_release_id。

⚠️ nac logs / smoke / test / bench / chat 省略环境名时，都会去打一个字面叫 default 的环境（多半不存在，于是你拿到一个跟真实环境无关的 404）。永远显式写环境名。

2.2 标准循环：改 → 发 → 确认真的生效

第三步不能省，它是全篇最硬的判据。

# ① 部署（stderr 会依次打印这些路标）
nac deploy staging
#   Packing artifact...
#     <N> bytes                     ← 这就是你的包大小，对照 100 MiB 上限用它
#   Creating version: v20260810-101530   ← tag = v<UTC yyyymmdd>-<HHMMSS>，自动生成
#   Uploading artifact...
#   Deploying <tag> to staging...
#   Waiting for version <id>...
#   Deployment status: <状态>       ← 每变一次打一行，中间穿插最近 30 秒的部署日志
# 默认最多等 10 分钟（--timeout 20m 可调；--no-wait 提交完就返回；--yes 跳过本地确认）

# ② 冒烟：真发一轮对话。退出码有区分度，可直接当 CI 卡口
nac --token "$AK:$SK" smoke staging --json
#   0 = 通过 / 1 = 失败 / 2 = 超时

# ③ ⭐ 确认这一轮跑的确实是新版本
curl -sS -u "$AK:$SK" "$BASE/agent-api/sessions/$SID/runs" | jq '.runs[0].versionId'

/runs 里的 versionId 是「我改的代码到底上去没有」的终极判据——它是这一轮实际执行的版本， 比界面上任何「部署成功」都可靠。和 nac versions list 里刚建的那个版本对一下即可。

nac deploy 的失败/超时会自动打印最近 10 分钟的部署日志再退出，退出信息形如：

Deployment failed for version <vid>: status=failed, message=<...>
Deployment timed out after 10m waiting for version <vid> (last status: deploying)

2.3 推荐的发布节奏

1. 内环：nac dev（临时泳道，不碰持久环境、不进部署历史）→ Playground 里点着试。
2. 预发：nac deploy staging → nac smoke staging →（有套件就）nac test staging --bail → 看 nac traces --last 1h 的错误与延迟。
3. 上线：把预发验过的那份制品重新上传部署到生产 —— nac deploy production。 ⚠️ 没有跨环境晋升，这一步是真的要再传一次。 ⇒ 风险也随之变了：不再是「两次打包结果不一致」，而是**「传上去的不是你验过的那个包」**。 确认你部署的就是预发验过的那份制品，别用工作区里改动过的代码重打。
4. 回滚：nac deploy <env> --promote <上一个稳定 tag> —— 切回本环境的老版本， 几秒完成，不需要重新打包。
5. 别动线上不确定的东西：只想让当前版本重启一遍用 nac versions redeploy <vid>（无损）， 不要用「删了再部一次」。

部署失败不伤线上：新版本起不来时环境指针不切换，老版本继续服务，新版本标 failed。 ⇒ 看到 403 VERSION_NOT_ACTIVE 时先分清是「新版本没起来」还是「线上真挂了」。

2.4 受保护环境：nac deploy 会 400，命令行没有开关能绕

Operating on environment '<name>' requires explicit confirmation. Set "confirm": true in request body.

• nac deploy（含 --promote）不发 confirm 字段；--yes 也不是它（--yes 只省掉本地那句 y/N 提示）。
• 唯一绕法是自己发一次带 confirm 的请求，语义完全等价（都是把环境指针切到已有版本）：

nac api PUT "/api/projects/$PID/versions/$VID/deploy" \
  --body '{"environment":"production","confirm":true}'

• ⚠️ 保护是每个环境自己的开关，跟名字无关：叫 production 的不会因为这个名字就自动受保护，叫 my-env 的也可能被开了保护。别靠名字猜，去查。 判据：控制台环境列表里那个琥珀色 protected 徽章，或 nac api GET "/api/projects/$PID/environments" 里的 requires_confirmation。
• 把这条命令先在 staging 上跑通再写进发布脚本，别等回滚时才发现它不通。

2.5 不可逆 / 有守卫的操作

3. 排障：固定次序（照走，别跳）

第 0 步：先把问题分成三类，分错类会在错误的证据面上耗掉几小时

第 1 步：把三个锚点存下来（事后补不回来）

curl -i -X POST "$BASE/agent-api/chat" -u "$AK:$SK" -d '...' 2>&1 | grep -iE 'server-timing|x-nac-|retry-after'

• trace id ← 响应头 server-timing: traceparent;desc="00-<32位十六进制>-<16位>-01" 中间那 32 位。 成功的响应也有，可直接 nac trace <id>，与 /runs、/actions 里的 traceId 是同一个值。
• request_id ← 只在错误响应体里（error.request_id，req_ 开头 26 位），每次错误都是新的。 你自己反查不了它，它的唯一用途是报障（§5）。
• session_id ← 你发起对话时用的那个。

第 2 步：看 HTTP 状态码 + message 原文，不要看 code

code 在两处会误导（详见 references/error-codes.md）：部分 4xx（含请求体校验失败、请求体超限） 的 code 恒填 INTERNAL_SERVER_ERROR；部分 403 的 code 恒填 VERSION_NOT_ACTIVE。 code 只适合做机读粗分类。

第 3 步：确认「到底哪个版本在服务这次请求」

curl -s "$BASE/agent-api/sessions/$SID/runs" -u "$AK:$SK" | jq '.runs[0]'

看 versionId。一步排除掉「改了没生效」这一整类问题。

第 4 步：看这一轮 run 的终态

同一个响应里的 status（submitted/working/input-required/completed/failed/canceled） 和 error.message。还停在 working 说明没跑完 —— 客户端断开不会停止 agent，要停必须显式 POST /agent-api/stop。

第 5 步：按阶段取证

第 6 步：走完 §5.3 的三条排除，再决定要不要报障

证据面总表（每一项的详细读法在 references/evidence-sources.md）

⚠️ /runs、/actions、/events 官方标注为 Experimental：契约可能在小版本内调整。 排障用它们没问题（本 skill 推荐的正是这个用法）；不要写死进生产集成—— 生产对话流走 POST /agent-api/chat 的内嵌 SSE。

4. 症状速查（完整版 27 条见 references/symptom-index.md）

5. 报障

5.1 这些你自己解决不了，别耗时间

• 500 / 503 —— 见到就报，没有自查空间。
• 持续 429 而你的并发并不高 —— 平台总容量不是你能调的（你能调的只有自己版本的副本上下限）。
• TRANSPORT_ERROR 的 message 里裹着 HTML 或 502 Bad Gateway，或短时间内成片的 LOCK_CONFLICT（几十上百次） —— 上游模型链路抖动，改代码没用。
• 部署起不来，而 ?previous=true 的崩溃日志里没有你自己的报错（日志为空或只有启动脚本输出）； 或部署进度卡住十几分钟不动。
• 需要开通出网白名单 / trace 存储 / 提高平台侧容量 —— 都要管理员审批或后台配置。

5.2 报障时提供（按价值排序，前三条能省掉大量来回）

5.3 报障前先自己排除这三条

1. 换一个新 session_id 重试 —— 还错说明与会话状态无关。
2. 换项目 AK/SK（而不是 PAT）重试一次 —— 排除 §4 那个 404 session not found 陷阱。
3. 拉一次 ?previous=true 的崩溃日志 —— 是不是自己代码报的错，一眼可辨。

错误信息是被刻意压平过的。 像 Failed to start Agent Runtime 这类文案不含根因。 根因在三个地方之一：?previous=true 的崩溃日志、trace 里 level = ERROR 那个 span 的 statusMessage、/actions 里 run_end 的 extra.reason。

6. ⚠️ 会骗你的判据（每条都「不报错、结果看着正常」）

按踩到的频率排。这一节的价值在于：它们全都不会以报错的形式提醒你。

1. GET /agent-api/chat/health 是静态返回 {"status":"ok"}，不检查运行实例、不检查部署。 它绿了什么都不能证明。 验证部署可用只有 nac smoke。
2. 界面 / CLI 的「部署成功」不等于生效 —— 部署是异步的，命令返回只代表任务已提交。 判据永远是 /runs 的 versionId。
3. nac logs 的 --last / --level / --grep 三个参数服务端不认，被静默丢弃 （--help 里那句 "Filters are combined server-side" 已过时）。 自证：nac logs <env> --level error 与 nac logs <env> 输出逐字相同。 替代：nac logs <env> --json | jq -r '.response.logs' | grep …，或 nac api 加 ?trace_id= / ?tail=2000。
4. nexau.json 的 setup 失败不会让部署失败 —— 只写一行 WARNING: setup command failed: 就继续。 「部署绿了」和「依赖装好了」是解耦的。
5. 错误信封的 code 字段不可信（见 §3 第 2 步）。
6. SSE 流干净地关闭 ≠ 跑完了 —— 服务端在某些异常下直接关流、不发任何错误帧。 判完成只能靠 5 个终态帧；没收到就回查 /runs，不要直接重发 /chat（会撞 409）。
7. /actions 的 limit 传超过 500 不报错、静默截到 500 —— 别据此断定「只有 500 条」。
8. /actions 默认只返回顶层 run，子 agent 的动作要传 parent_run_id 才看得到（一次下钻一层）。 不传就看不到，很容易误判成「子 agent 根本没跑」。
9. /runs 的 variables 里敏感值被打码成 ***REDACTED***，且是按键名子串匹配，会误伤 tokens_per_minute 这类普通业务字段。⇒ 看不到值 ≠ 没传成功；想确认传没传，看键在不在。
10. /runs 的 error 字段缺席 ≠ 没出错 —— 失败原因是三级回落： /runs.error.message → /actions 里 run_end.extra.reason → trace 里 ERROR span 的 statusMessage。
11. nac trace --export 上游中途出错时返回 502 但响应体仍带已拉到的部分，CLI 按成功处理、 只在 stderr 提示 ⚠ upstream error after <N> observations —— 脚本里只看退出码会误判成成功。
12. /actions 与 /runs 的 status 是两套词表（前者 in_progress/ok/succeeded/failed/ error/cancelled…，后者六值 A2A 词表）。判终态以 /runs 为准，别混着断言。
13. nac deploy --dry-run 不会真打包，所以看不到那行 <N> bytes。想知道包多大只能真跑一次。
14. 缩到 0 或还没起来时 nac logs 返回 503 / nac versions logs 返回 404 —— 那不代表服务坏了，先发一次对话把它唤醒再看。
15. POST /agent-api/stop 返回 {"status":"noop"} 不是失败 —— 意思是当前没有正在跑的 run， 没什么可停，这是成功语义。

7. 平台限制：一页速查（数值与自测法见 references/platform-limits.md）

⚠️ 带「约」字的都是部署级默认值，私有化部署可能不同。当量级用，别写死进代码， 每条在 references 里都给了你自己能跑的判据。

你自己能改的（控制台 项目设置）：Runtime CPU/内存上限、三维拒流阈值（资源上限 tab）； 最小/最大副本、扩缩容阈值、缩零闲置小时（负载均衡 tab，也可 nac versions scaling）； 环境变量与模型（运行配置 tab，也可 nac vars）；出网白名单申请（网络策略 tab，仅项目 owner 可见，需管理员审批）。 你改不了的：沙箱 CPU/内存/磁盘、沙箱闲置暂停时长、持久路径清单、非流式超时、制品与请求体上限、隔离档位。