Pi Webpi 编程智能体 Web 界面从本地部署到远程访问实战【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-webPi Web 是 pi 编程智能体的本地浏览器界面它与 pi 终端共用同一份配置和会话文件让你在浏览器里查找并继续历史对话、运行智能体、管理模型与 Provider。本文覆盖一键启动、参数配置、远程访问加固的完整流程并解析端口解析、认证与文件安全边界背后的源码实现。场景与定位Pi Web 的价值可以用三个真实场景说清续接终端会话你在 pi 终端里跑了半天的会话切到 Pi Web 里就能按项目找到它、继续对话、导出 HTML不用复制粘贴。网页里管模型不想打开终端改配置Pi Web 的 Models 面板可以直接登录 Provider、粘贴 API Key、测试模型连通性。可信局域网共享同事在你局域网内访问你的 Pi Web 实例各自操作各自的项目会话。关键在于数据边界Pi Web 与 pi 共用本机数据目录~/.pi/agent会话文件以 JSONL 格式存放在sessions/编码后的工作目录/时间戳_uuid.jsonl模型配置则共用~/.pi/agent/models.json。两边对同一份文件的修改互相可见——这也是为什么浏览会话是纯只读操作直接读 JSONL不创建任何 AgentSession 运行时。能力速览按使用场景分组浏览与续接历史会话会话按项目分组展示支持重命名、归档、导出与删除并实时显示运行状态、上下文占用与花费。分支有两种语义不要混淆新会话从较早消息 fork 出一个独立的.jsonl文件从此处编辑调用navigate_tree在同一文件内切换分支多条目共享parentId。前者实现于lib/session-fork.ts后者由hooks/useAgentSession.ts发送纯浏览读取则走lib/session-reader.ts。切换模型与 ProviderModels 面板读写 pi 的模型、设置与凭据存储包含 API Key 登录、OAuth 设备码流程、模型目录刷新与单模型连通性测试对应路由在app/api/models-config/与app/api/auth/界面组件为components/ModelsConfig.tsx。文件与 Git 协作侧边栏文件树可浏览、上传、预览源码 / Markdown / 图片 / 音频 / PDF / DOCX并自动刷新Git 变更与单文件 Diff 由/api/git提供。Worktree 切换器能把同一仓库不同 worktree 的会话归组展示解析逻辑在lib/worktree.ts——它利用git rev-parse --git-common-dir把 linked worktree 指回主仓库根。远程与团队使用设置PI_WEB_PASSWORD后浏览器走密码登录页API 客户端可用用户名为pi的 Basic Auth 调用机制详见下文安全章节proxy.ts、lib/web-auth.ts。从零跑起来最小可运行路径只有三步检查 Node 版本node --version需22.19.0 或更高package.json的engines强制约束入口脚本bin/pi-web.js启动前也会校验不满足直接报错退出。启动npx agegr/pi-weblatest。验证服务就绪后 CLI 会尝试自动打开浏览器没有打开就手动访问http://127.0.0.1:30141。默认监听地址是127.0.0.1仅回环端口30141二者都可用-p/-H或环境变量覆盖。全局安装与更新npm install -g agegr/pi-weblatest pi-web更新前先pi-web stop或CtrlC再执行pi-web update或重复安装命令卸载用npm uninstall -g agegr/pi-web。CLI 还提供version、status、stop、open等子命令管理已运行的服务。源码开发npm install npm run dev开发服务器同样运行在 http://127.0.0.1:30141且默认不会自动打开浏览器由next dev直接启动。常用检查命令npm test # 运行 app/components/hooks/lib/public 下全部测试 node_modules/.bin/tsc --noEmit # 类型检查 npm run lint # ESLint 检查参数与配置一张表参数或变量作用默认值--help、-h打印启动选项并退出不启动服务—--port 端口、-p 端口或PORT服务端口30141--hostname 主机、-H 主机或PI_WEB_HOSTNAME监听主机名127.0.0.1--no-open或PI_WEB_NO_OPEN1不自动打开浏览器自动打开PI_WEB_ALLOWED_HOSTS额外允许的代理/自定义主机名逗号分隔精确匹配未设置PI_WEB_PASSWORD启用密码登录API 客户端可用用户名pi的 Basic Auth不启用认证PI_WEB_APP_NAMEPWA manifest 名称需重启生效Pi WebPI_WEB_SKIP_VERSION_CHECK设为 1 关闭更新检查未设置PI_WEB_IDLE_TIMEOUT_MS会话空闲超时毫秒0禁用60000010 分钟PI_WEB_SHUTDOWN_DEADLINE_MS关闭时扩展处理session_shutdown的宽限毫秒5000优先级规则是命令行 环境变量 默认值解析逻辑集中在bin/pi-web-options.js的parseLaunchOptions()。两个易错点端口必须是 065535 的整数否则启动直接抛错布尔型环境变量如PI_WEB_NO_OPEN接受1/true/yes/on四种取值。传入未知参数会以退出码 1 报错并提示使用--help。网络与安全边界默认监听127.0.0.1意味着 Pi Web 只接受本机回环流量局域网内其他设备无法访问——对一个能执行高权限操作的智能体来说这是最保守也最安全的默认值。一旦你把它绑到非回环地址就要认真处理下面三件事。密码认证配置步骤设置PI_WEB_PASSWORD即启用认证入口拦截由proxy.ts的proxy()统一接管匹配/、/login与/api/:path*未认证的页面访问重定向到/login未认证的 API 请求返回401并携带WWW-Authenticate: Basic realmPi Web头。lib/web-auth.ts的细节值得看一眼Basic Auth 用户名固定为piPI_WEB_AUTH_USERNAME常量密码即环境变量值密码比较先做 SHA-256 摘要再走timingSafeEqual规避时序侧信道登录成功签发pi_web_sessionCookie用 HMAC-SHA256 签名、有效期 30 天后续请求凭它通过校验连续失败会触发限流lib/auth-throttle.ts返回429Retry-After防止暴力猜解。⚠️密码认证 ≠ 连接加密。它只是让访问者登录HTTP 明文传输下密码和流量照样可见切勿据此把服务暴露到互联网。远程暴露的正确姿势在可信局域网中使用时务必设置足够长的随机密码PI_WEB_PASSWORD足够长的随机密码 pi-web --hostname 0.0.0.0bin/pi-web.js会检测监听地址非回环且无密码时输出 without authentication 警告即使启用了密码也会提醒 HTTP 明文无法保护传输中的密码。正确姿势是可信反向代理提供 HTTPS或走可信 VPN绝不明文暴露公网。Host 白名单与反 DNS-rebindinglib/request-security.ts的isApiRequestHostAllowed()只信任三类 Host本地名localhost及*.localhost、IP 字面量、以及操作者显式配置的主机名PI_WEB_HOSTNAMEPI_WEB_ALLOWED_HOSTS。这个设计的巧妙之处在于IP 字面量保留了局域网访问能力而浏览器在 Host 头中会原样保留字面地址攻击者无法用 DNS rebinding 把恶意域名解析到127.0.0.1来骗过校验。同文件还实现了 CSRF 防护isApiRequestAllowed()会拒绝sec-fetch-site: cross-site的浏览器 API 请求只放行非浏览器客户端与同源请求并兼容反向代理改写Origin的场景。如果代理会传递外部主机名记得把该名称精确加入PI_WEB_ALLOWED_HOSTS——它是精确匹配而非通配且不会改变 Pi Web 的监听地址。代理与离线网络服务端的模型与 API 请求走 undici 的EnvHttpProxyAgentlib/http-dispatcher.ts中configureHttpDispatcher()因此标准代理环境变量开箱即用。macOS / LinuxHTTP_PROXYhttp://127.0.0.1:7890 \ HTTPS_PROXYhttp://127.0.0.1:7890 \ NO_PROXYlocalhost,127.0.0.1 \ npx agegr/pi-weblatestWindows PowerShell$env:HTTP_PROXY http://127.0.0.1:7890 $env:HTTPS_PROXY http://127.0.0.1:7890 $env:NO_PROXY localhost,127.0.0.1 npx agegr/pi-weblatest源码地图精选不穷举app/ Next.js 界面与 API 路由 components/ React 界面组件 hooks/ 客户端状态与交互 hooks lib/ 会话、智能体、模型、文件、Git 与安全逻辑 bin/ npm CLI 入口与启动参数解析 docs/ 面向用户与贡献者的专题文档值得深入的文件CLI 入口bin/pi-web.js—— Node 版本检查、参数解析、拉起next start子进程、服务就绪后打开浏览器选项解析bin/pi-web-options.js—— CLI 与环境变量优先级、端口校验、子命令分派认证中间件proxy.ts—— 全入口的认证与限流闸门请求安全lib/request-security.ts—— Host 白名单、反 DNS-rebinding 与 CSRF 校验会话读取lib/session-reader.ts—— 只读 JSONL 的浏览通道不创建运行时智能体运行时lib/rpc-manager.ts——startRpcSession()在进程内创建AgentSession事件经 SSE 推给前端文件边界lib/file-access.ts与lib/path-security.ts——/api/files的允许根与isPathWithinRoots()统一裁决。使用注意事项 / 常见问题数据目录默认读~/.pi/agent可用PI_CODING_AGENT_DIR指向其他 agent 目录该环境变量在lib/http-dispatcher.ts的defaultAgentDir()中解析支持~与 Windows 盘符路径归一化。同一文件系统环境Pi Web 必须能读到 agent 数据目录及会话记录中的工作目录。与已有 pi 会话共用数据时让它与 pi 运行在同一台机器/同一容器内别试图跨主机读本地路径。文件 allow-list 边界文件浏览器只覆盖你在 Pi Web 中选过的工作目录、已识别的项目根/会话根及~/pi-cwd-*目录它不是通用文件系统浏览器——所有路径裁决收敛在lib/path-security.ts。别在开发期跑构建日常开发不要执行next build/npm run build它会污染.next/并干扰开发服务器构建只属于发布流程。遇到端口占用先lsof -nP -iTCP:30141 -sTCP:LISTEN复用健康的已有进程两个next dev会争用.next/dev/lock。会话回收空闲 10 分钟后 AgentSession 会被回收默认值长任务可用PI_WEB_IDLE_TIMEOUT_MS0禁用自动回收。许可证Pi Web 采用 MIT 许可证。【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-web创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考