Pi Web 的这个教程只处理标题中的具体任务。Pi Web 默认只监听 127.0.0.1，而且没有应用层认证；它能调用高权限 Agent，因此远程访问首选 SSH 本地转发，而不是直接绑定 0.0.0.0。
下面所有操作都先放在测试仓库、测试账号或仅回环监听的服务中。命令中的域名、用户名、路径与密钥是占位符，执行前需要替换。
先理解 Pi Web 的无认证边界
这一节解决的是“先理解 Pi Web 的无认证边界”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 Pi Web 而言，判断依据是：Pi Web 默认只监听 127.0.0.1，而且没有应用层认证；它能调用高权限 Agent，因此远程访问首选 SSH 本地转发，而不是直接绑定 0.0.0.0。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
Node.js 22.19 版本检查
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“Node.js 22.19 版本检查”有可重复结果。
保持回环监听启动服务
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 保持回环监听启动服务 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
SSH 本地端口转发的完整路径
围绕“SSH 本地端口转发的完整路径”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
从客户端确认端口只在本机开放
这一节解决的是“从客户端确认端口只在本机开放”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 Pi Web 而言，判断依据是：Pi Web 默认只监听 127.0.0.1，而且没有应用层认证；它能调用高权限 Agent，因此远程访问首选 SSH 本地转发，而不是直接绑定 0.0.0.0。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
多用户服务器如何隔离会话文件
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“多用户服务器如何隔离会话文件”有可重复结果。
为什么不建议直接使用 0.0.0.0
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 为什么不建议直接使用 0.0.0.0 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
必须反代时增加哪些保护
围绕“必须反代时增加哪些保护”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
代理环境变量如何传给服务端请求
这一节解决的是“代理环境变量如何传给服务端请求”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 Pi Web 而言，判断依据是：Pi Web 默认只监听 127.0.0.1，而且没有应用层认证；它能调用高权限 Agent，因此远程访问首选 SSH 本地转发，而不是直接绑定 0.0.0.0。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
隧道断开与页面假在线
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“隧道断开与页面假在线”有可重复结果。
关闭服务并清理残留端口
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 关闭服务并清理残留端口 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
远程访问验收清单
围绕“远程访问验收清单”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
限制 SSH 转发账号
这一节解决的是“限制 SSH 转发账号”。先记录当前状态，再执行最小动作，最后用独立证据确认结果。
对 Pi Web 而言，判断依据是：Pi Web 默认只监听 127.0.0.1，而且没有应用层认证；它能调用高权限 Agent，因此远程访问首选 SSH 本地转发，而不是直接绑定 0.0.0.0。不要在这个阶段顺手打开更多权限。
|
|
执行后保留命令输出和时间戳。若输出依赖当前终端里的临时变量，打开新终端复查一次。
Pi 会话文件的备份边界
按下面顺序处理：
- 读取实际版本和当前配置。
- 只改变与本节相关的一项设置。
- 运行一个只读或可撤销的请求。
- 检查日志、退出码和最终文件。
- 失败时恢复刚才那一项修改。
|
|
这里的完成标准不是界面出现，而是“Pi 会话文件的备份边界”有可重复结果。
反代认证失效立即停用路由
| 要检查的内容 | 合格表现 | 需要停止的信号 |
|---|---|---|
| 反代认证失效立即停用路由 | 输入和输出范围明确 | 自动扩大到其他项目或账号 |
| 权限 | 只获得完成任务所需权限 | 要求管理员权限或完整密钥 |
| 日志 | 能定位失败且已经脱敏 | 出现 Token、Cookie 或私有正文 |
| 回退 | 能恢复上一步状态 | 修改不可逆且没有备份 |
|
|
表格中的停止信号一旦出现，先撤销本节改动，不要继续后面的自动化。
升级后复查监听地址
围绕“升级后复查监听地址”准备一个成功样本和一个失败样本。成功样本验证正常路径，失败样本验证限制是否真的生效。
|
|
建议记录以下四项：
- 执行前的版本或 Git 提交。
- 实际输入，不记录秘密值。
- 可观察的输出、状态码或 diff。
- 恢复动作以及恢复后的复查结果。
如果失败原因仍不清楚，每次只修改一个变量；不要同时换端口、运行时、Provider 和代理。
Pi Web 常见问题
是否可以跳过测试环境，直接把 Pi Web 用到正式项目？
不建议。至少先完成一次最小成功请求、一次故意失败和一次恢复演练。
Pi Web 命令能运行但结果不对，先查哪里？
先查输入范围、实际生效的配置和上游响应，再查模型总结。进程正常不代表业务结果正确。
如何避免 Pi Web 的密钥或令牌进入 Git？
使用系统环境变量、Secret 管理或项目外配置文件，并在提交前搜索 diff。发现泄露后必须轮换密钥。
升级 Pi Web 时最容易漏掉什么？
最容易漏掉配置格式、默认监听地址、权限范围和缓存兼容性。升级前保存版本与验证样本。
Pi Web 验收问题
完成后应能回答下面的问题：
- 使用的是哪个确切版本？
- 哪些目录、端口、账号和外部服务可被访问？
- 成功结果如何回到原始数据或 Git diff？
- 上游失败时会报错、重试还是切换？
- 密钥是否可能出现在日志或历史记录？
- 如何在十分钟内回到修改前状态？
如果其中任何一项无法回答，Pi Web 仍处于试用状态，不应扩大权限或接入生产自动化。