安全与隐私

本页说明 pi-webapp 能保护什么、不能保护什么，你的数据存在哪里，哪些内容会离开你的机器，以及怎样安全地使用。

简短版本

• 服务只监听你自己的机器（127.0.0.1），并且需要一个随机访问令牌，这个令牌就在你打开的地址里。
• 它不是沙箱。 代理和每个终端都以你的用户权限运行，能读取、修改和删除你能操作的任何东西。
• 你的凭据和会话历史保存在你磁盘上 Pi 的数据目录里。
• 你的消息和附件会发给你选定的模型提供方。默认情况下不会向其他任何地方发送东西，错误上报也是关闭的。

网络暴露与访问令牌

服务启动时，会在 127.0.0.1 的一个随机空闲端口上监听。它不监听你的网络接口，所以其他机器不能直接访问它。它打印出的地址形如：

http://127.0.0.1:52395/#im0P2eSzuw1xH6Vmhr2Z2hjpLoy8I8qy

# 之后的部分是一个随机的 192 位令牌。页面读取它，并把它作为 bearer 令牌附在发往服务 /api/ 路由的每个请求上。没有有效令牌的请求会被拒绝，返回 HTTP 401；来自其他网页来源的修改类请求也会被拒绝。页面本身带有严格的内容安全策略：脚本和样式只能来自这个服务，也不允许其他网站嵌入它。

实际含义是：

• 把完整地址当作密码。 任何拿到它、又能连到那个端口的人，都能操控你的代理和终端。不要把它贴进聊天、工单，也不要贴带地址栏的截图。
• 这个地址会留在浏览器历史和书签里。在共用的电脑上，请使用无痕窗口或清除记录。
• 同一台机器上的其他用户可以连到这个端口，但没有令牌就无法使用。启动器把地址存在一个只有你的用户能读的文件里（pi-web/launcher.json）。
• 令牌在每次服务重启时都会变，只有一个例外：应用内的 升级并重启 会保留原来的端口和令牌，让你的页面重新连上。/web 的令牌只在那个 Pi 进程存活期间有效。

远程机器

永远不要把服务绑定或代理到公网地址，也不要公开转发后的 URL。要使用运行在另一台机器上的服务，请通过 SSH 这类私密通道转发它的端口，并且两端使用相同的端口号：

# 在远程机器上：查看端口
npx pi-webapp status
# 在你自己的电脑上：转发那个端口（这里以 52395 为例）
ssh -L 52395:127.0.0.1:52395 you@remote-host

然后在本地浏览器里打开带令牌的完整地址。

端口号必须一致，是因为服务只接受来源恰好等于它所打印地址的请求。如果你转发到了本地的另一个端口，页面能加载，但会显示 来源不匹配，实时功能也会失效。通过 SSH 连接时，启动器不会尝试打开浏览器，添加工作区 也会改用 pi-webapp 自带的文件夹浏览器，而不是系统原生的。

代理和终端能做什么

• 代理可以读取、创建、编辑和删除文件，也可以运行 shell 命令，范围是你的用户能到达的任何地方。选择工作区只决定它从哪里开始，而不是它能去哪里。
• 终端就是你的登录 Shell。工作区只是起始目录。
• 文件预览的范围比这窄：它只读取工作区内部，也不会跟随符号链接走出去。这限制的是预览工具，而不是代理。
• Git 写操作（提交、切换分支）会检查状态是否过期，并等待共用工作树的会话空闲。它们是防止误操作的护栏，不是访问控制。

实用的习惯：

• 从项目目录启动服务，而不是从你的主目录。
• 允许改动之前，先要一个计划或一段只读的解释，并在提交前用 Git 工具审阅差异。
• 让不能丢的工作处在版本控制之下。
• 不要把它指向一个放着密钥的目录，除非那些内容你自己也愿意粘贴给模型提供方。

你的数据存在哪里

一切都在 Pi 的数据目录下，默认是 ~/.pi/agent（PI_CODING_AGENT_DIR 可以改变它）。完整的对照见文件与目录。

内容	位置	说明
会话	sessions/	完整的对话历史，包括工具输出。
凭据	auth.json	只有你的用户可读。不会返回给浏览器。千万不要附在报告里。
模型配置	models.json	不含 Key，但可能含有私有地址。
pi-webapp 状态	pi-web/	工作区列表、上传的附件、插件数据、启动器状态和日志。

你上传的附件会复制到 pi-web/attachments/ 下。把工作区从侧栏移除，不会删除以上任何内容。

哪些内容会离开你的机器

内容	发给谁	什么时候
你的消息、工具输出、附加的文件	你的模型提供方	每次请求。适用该提供方的数据政策。
包和版本的下载	npm 仓库、GitHub	用 npx 启动、检查或安装更新，或下载 Excalidraw 这类插件时。
错误报告	Sentry	除非你打开，否则从不发送。

本地网页不等于本地推理。如果你需要什么都不离开本机，就把自定义提供方指向运行在本机上的模型服务（模型与提供方）。

错误上报

Sentry 错误上报默认关闭。仅仅配置了上报目的地（DSN）并不会启用它；它需要在启动服务的进程的环境里设置 PI_WEB_SENTRY_ENABLED=true。如果你从不设置它，就不会上报任何东西，也不需要你做任何设置来保持退出状态。

开启之后，上报内容仅限于经过脱敏的堆栈跟踪、事件面包屑和状态摘要。对话、文件内容、附件、凭据、请求体和会话录屏不会被有意收集，但任意的错误文本无法被完美分类，所以请不要把私密数据写进错误信息里。详情见 Sentry 说明。

如果你设置过又想关掉，取消这个变量或设为 false，然后重启服务。

插件、包和扩展

• Pi 包、扩展和技能与 Pi 拥有相同的权限。就像对待你机器上运行的任何代码一样，只从你信任的来源安装。
• Excalidraw 这类可选插件以经过校验的包的形式来自 npm。它们运行在单独的 Node.js 进程里，页面运行在单独的浏览器框架里，这把它们的生命周期与主页面隔开。这不是针对恶意代码的沙箱。
• Excalidraw 完全在本地运行，没有 Excalidraw 云服务、协作或上传。

安全地报告漏洞或问题

普通的缺陷请提 issue。不要在公开的 issue 里贴令牌、访问地址、auth.json、私钥或私密对话；先把问题缩减成一个最小示例。本项目目前没有公开的私密安全联系方式，所以如果某个漏洞公开披露会有危险，请开一个 issue 描述涉及的范围，但不要写出利用细节，并请求一个私密沟通渠道。