Pi Plus · 技术架构与实现分析文档

pi.haoaiganfan.top · 服务器 110.40.142.210 · 文档版本 v1.0 (2026-09-15)

架构分析实现原理功能规划

Pi Plus（pi-web-plus） 是部署在本机（root@110.40.142.210）的 coding agent Web 工作台，基于 Vite + React + TypeScript 前端与 Node.js ESM 后端，提供多会话并发、流式对话、工程面板（文件/Git/Skills/Tools）、模型路由与密钥管理、会话分享等能力的自部署 AI 面板。本文档对系统做系统性梳理，面向团队协作者与后续维护者。

📑 目录

系统架构分析 — 部署拓扑、五层架构、模块关系图、端口规划、数据持久化
实现原理分析 — 会话管理、模型路由、上下文监控、分享导出、安全鉴权
新功能规划 — 需求分析、技术方案、工作量评估与优先级排序
附录 — 关键文件清单、API 速查、排障命令

1系统架构分析

Pi Plus 采用经典的 前后端分离 + 反向代理 架构，整体分为五层：浏览器客户端 → Nginx 入口 → Node 后端 → AI 智能体引擎 → 数据存储。各层职责清晰，通过 HTTP/HTTPS 与 SSE 事件流通信。

架构全景五层部署拓扑

浏览器客户端
HTTPS 443
React SPA

▼

Nginx 1.26
静态托管 + /api/ 反代
SSL 终止

▼

Node 后端
127.0.0.1:3067
systemd 托管

▼

AI 引擎
@earendil-works/pi-coding-agent
多模型 / 工具 / 权限

▼

数据存储
/root/.pi/agent/
JSONL / JSON

逐层详解

第 1 层 · 客户端 Browser · SPA

技术栈：Vite 6 + React 19 + TypeScript + Rolldown 构建。纯前端无桌面客户端。

构建产物：frontend-next/dist/（index.html + hash assets）

UI 框架React 19 + 自定义组件库（Sidebar / Panel / Composer / MessageList）

状态管理React Context + useReducer（SessionProvider / Toast / Dialog / Prefs）

流式通信SSE（EventSource）+ rAF 节流 live 渲染

主题明/暗双主题，localStorage 持久化

移动端左侧边栏 + 手势返回 + 触控优化

错误监控onerror / unhandledrejection / React 边界，限流去重上报

第 2 层 · 入口层 Nginx 1.26.3

角色：静态资源托管 + 反向代理 + SSL 终止 + gzip 压缩。

静态托管frontend-next/dist（Vite 产物）
/assets/ 30d immutable · /fonts/ 共用库 · try_files → index.html

/api/* 反代→ 127.0.0.1:3067
proxy_buffering off · 读写超时 86400s · client_max_body_size 32M

静态库/fonts/ → /var/www/libs/fonts/ · github.css → /var/www/libs/
immutable 长缓存，独立版本管理

多域名pi / pi-v2 共用前端片段 · 3067 子域 301 跳转 · 其他业务子域独立配置

SSL 证书：/etc/nginx/ssl/haoaiganfan.top/fullchain.pem + privkey.pem · TLS 1.2/1.3

第 3 层 · 后端核心 Node ESM · server.mjs

入口：/opt/pi-web-plus/backend/src/server.mjs（2589 行 ESM 模块）。运行方式：systemd pi-web-plus.service，Restart=always。

环境变量：PORT=3067 · HOST=127.0.0.1 · PI_WEB_PASSWORD（密码）· PI_WEB_CWD=/root · PI_WEB_PLUS_STATIC=frontend-next/dist

路由域auth(3) · session(24) · content(20) · tools(18) · config(18) = 63+ 端点

SessionSlot 池每会话 = 独立 runtime + 权限门 + Plan 模式 + 队列 · 空闲槽上限 8 · LRU 回收

SSE 事件流eventLog 上限 800 条 · Last-Event-ID 对账 · build 版本软刷新 · 指数退避重连

消息队列queue/steer/followUp 三种递话策略 · 磁盘持久化(web-queues.json)

定时任务schedules.json · cron/间隔/每日/单次四种类型 · 失败自动推送

推送通知Telegram Bot / Bark · turnEnd / perm / error 三类事件 · 60s 节流

第 4 层 · AI 引擎 @earendil-works/pi-coding-agent ^0.84.2

角色：智能体核心 — 模型管理、工具执行、会话生命周期、权限系统。

ModelRuntime多模型 / 思考等级 / API Key 管理 / 可用模型发现

工具系统bash / write / edit / read / grep / find / ls / git / skill

权限门禁ask / allow / deny 三档策略 · 危险工具弹窗确认

Plan 模式只读探索 · 自动关闭 write/edit · 强制保留 read/bash

插话策略queue(队列) / steer(插话) / followUp(跟进) · /btw 阅后即焚

斜杠命令/new /fork /compact /export /plan /settings /btw /cron 等 17 个

第 5 层 · 数据持久化 /root/.pi/agent/

会话数据

sessions/ — JSONL 格式，每行一条事件（message / toolCall / toolResult / compaction…）
sessions-archive/ — 归档（软删除 / 压缩前备份）
web-prefs.json — 按会话隔离的 Plan/权限/插话/工具配置
web-queues.json — 消息队列磁盘持久化

模型与认证

models.json — Provider 配置 + 模型列表（可读写）
auth.json — API Key（原子写 · 权限 600 · 脱敏显示）
settings/ — SDK 全局设置

工程与任务

web-schedules.json — 定时任务
push.json — 推送配置(Telegram/Bark)
resumes/ — 429 续跑任务
skills/ — 技能定义
notebook.md — 跨会话笔记本

静态资源

/var/www/libs/ — 字体 / GitHub CSS / 第三方库
/var/www/pi-design/ — /design 架构说明页
/var/www/pi-share/ — /share/ 会话外链

端口与进程规划

端口	协议	绑定	服务	进程/管理	说明
80	HTTP	0.0.0.0	Nginx	nginx master	HTTP→HTTPS 301 跳转
443	HTTPS	0.0.0.0	Nginx	nginx master/worker	SSL 终止 + 反代 + 托管
3067	HTTP	127.0.0.1	Node(pi-web-plus)	systemd pi-web-plus.service	后端 API，仅内网可达
8080	HTTP	127.0.0.1	python3	独立进程	其他业务服务
8081	HTTP	127.0.0.1	node(editor-server)	独立进程	编辑器服务
8082	HTTP	127.0.0.1	python3(ip服务)	独立进程	IP 查询服务
8088	HTTP	0.0.0.0	Nginx	nginx worker	看板/监控面板
9801	HTTP	127.0.0.1	node(boat)	独立进程	其他业务

后端 Node 进程内存上限 1536MB（--max-old-space-size=1536），当前运行 9 个会话槽，内存 251.8MB。

2实现原理分析

2.1会话管理与状态广播

核心模型：SessionSlot 池

多会话并发：每个会话文件（JSONL）对应一个 SessionSlot（2590 行 server.mjs 中定义），包含独立 runtime / 权限门 / Plan 模式 / 消息队列。
切换不中断：切换会话只修改 activeSessionFile，其他会话的流式回合完全不受影响。
LRU 回收：空闲（未激活且未运行）槽上限 8（MAX_IDLE_SLOTS），超出后回收最久未活跃的。
权限按会话：每个 Slot 持有一份 createPermissionGate() 实例，策略（ask/allow/deny）按会话隔离。
状态广播：通过 SSE（/api/events）推送 t:state/hello/mu/me/as/ae 等事件，前端按当前会话过滤。

SSE 事件流与断线重连

事件序列号：全局 eventSeq 递增，每个事件带 eid，供 Last-Event-ID 对账。
eventLog：内存保留最近 800 条事件，断线后回放增量事件。
心跳：每 15s 推送 t:ver（含 build 版本），前端检测到版本变化自动软刷新。
重连策略：前端 connectEvents()（sse.ts）使用指数退避（0.5s→16s），最多 6 次。
tail/窗口：API 返回尾部 40 条（默认），/api/state?limit=N 可调（1-200）；full=1 返回全量。

消息队列与递话策略

queue：繁忙时消息入队，按序逐条发送（persisted to web-queues.json）
steer：繁忙时立即注入当前回合（阅后即焚，不留痕）
followUp：本轮结束后自动跟进
/btw：独立内存会话，noTools，主会话零影响（btwChats Map 存储，60s 清理）

2.2模型路由与密钥管理

模型配置结构

models.json：{ providers: { "openrouter": { models: [...], baseUrl, api }, "deepseek": {...}, "bigmodel": {...} } }
通过 /api/config/models 读写，设置页可视化 CRUD
auth.json：{ "provider": { type: "api_key", key: "..." } }，原子写（临时文件 + rename），权限 600

模型发现与过滤

modelRuntime.getAvailable()：SDK 层发现所有可用模型
OpenRouter 免费过滤：selectableModels() 只保留 openrouter/free 或 :free 后缀，防止 UI 误选付费模型
/api/models 返回可选项；/api/config/models 返回含脱敏凭证的完整配置

密钥持久化与脱敏

setProviderApiKey()：先写运行时 → 再写 auth.json（原子写）
listCredentialsMasked()：只返回 provider + type + hasKey，不暴露 Key 值
listAuthProviders()：Fallback 从 auth.json 读 key 存在性
会话级模型：setSessionModel() 用 muteMethod 拦截 SDK 的 setDefaultModelAndProvider 写全局操作，保证会话隔离

2.3上下文监控与资源统计

Token 用量统计

currentState() 汇总所有 assistant 消息的 m.usage：input / output / cacheRead / cacheWrite / cost
getSessionStats()：SDK 层统计 userMessages / assistantMessages / toolCalls / toolResults / totalMessages
tokenUsage 结构：{ input, output, cacheRead, cacheWrite, total, cost }
显示位置：聊天区底部 / 侧栏 SessionRow

上下文粒子指示器（ctx）

getContextSafe() → session.getContextUsage()：返回 { tokens, contextWindow, percent }
前端显示进度条，颜色随 percent 变化（绿→黄→红）
compaction：压缩摘要信息（summary / tokensBefore / timestamp），缓存于 slot.compactionCache
压缩流桥接：installCompactionStreamBridge() 将 SDK 的 streamFunction 输出转成 t:ms/t:mu SSE 事件，让用户实时看到压缩进度（原为死代码）

2.4分享与导出

会话分享（/share/）

POST /api/share/session：提取会话中的 user/assistant 消息，生成纯 HTML 页面
文件名随机（share-{randomBytes(6).hex}.html），防枚举
存放 /var/www/pi-share/，Nginx ^~ /share/ alias 托管
HTML 仅保留用户↔助手对话，去掉工具执行噪音，支持展开全文

多格式导出

POST /api/session/export?format=jsonl：调用 SDK exportToJsonl()，输出到 /tmp/pi-web-plus-exports/
format=html：SDK exportToHtml()
format=md：自实现 Markdown（用户/助手文本主干 + 工具调用折叠摘要）
下载地址：/api/session/export/file?name=session-xxx.{jsonl|md|html}（正则校验文件名防路径穿越）

工程文件浏览

/api/files：列出文件（支持 showHidden 开关）
/api/file：读取文本文件（限制 256KB，二进制拒绝）
/api/file/download：流式下载（resolveSafe 防路径穿越）
隐藏文件开关：前端传 showHidden=1 参数，后端 listDir() 的 showHidden 参数控制是否显示点文件（.gitignore 始终显示）
/api/browse：绝对目录浏览（带路径校验）

2.5安全鉴权

HMAC Token 认证

createAuthToken(secret)：生成 {id}.{exp}.{HMAC-SHA256签名}，TTL 7天
verifyAuthToken(token, secret)：验证签名 + 过期时间，使用 timingSafeEqual 防时序攻击
双重携带：Authorization: Bearer Header 或 Cookie piweb_plus_token（HttpOnly · SameSite=Lax）
重启后仍有效：token 由密码派生，不依赖进程状态
密码来源：systemd override.conf 中的 PI_WEB_PASSWORD 环境变量（当前值已配置）

权限门禁

createPermissionGate()：每个 Slot 独立实例
危险工具：bash / write / edit 触发 tool_call 事件 → emit t:perm SSE → 前端弹窗确认
三档策略：ask（需确认）/ allow（放行但记录）/ deny（拦截并反馈给模型）
超时：120s 未确认自动拒绝
会话隔离：各会话的 allow 列表独立，clearSessionAllows() 可清空

其他安全措施

路径穿越防护：resolveSafe() 检查 ..；archiveFileOf() 限制只在会话目录内
工具配对自愈：sanitizeToolPairs() 清洗孤儿 toolResult / 落单 toolCall（防 OpenAI 兼容接口 400）
前端错误上报：限流（每分钟≤10条）+ 去重（30s 内相同错误只报一次）
健康检查：GET /api/health 返回 ok/name/build/cwd/slots
fail2ban：防 SSH 爆破（系统级）

2.6关键代码位置索引

功能	文件/位置	关键函数
后端入口	backend/src/server.mjs	handleApi, broadcast, currentState, createSlot, bindSlot
认证	backend/src/lib/auth.mjs	createAuthToken, verifyAuthToken, extractAuthToken
会话路由	backend/src/routes/session.mjs	sessionRouter（/api/session/, /api/events, /api/share/）
模型配置	backend/src/lib/models-config.mjs	read/writeModelsFile, setProviderApiKey, listCredentialsMasked
权限门禁	backend/src/lib/permissions.mjs	createPermissionGate, DANGEROUS set
Plan 模式	backend/src/lib/plan-mode.mjs	createPlanModeExtensionFactory, PLAN_MODE_PROMPT
/btw 侧问	backend/src/lib/btw.mjs	runBtwChat, createBtwExtensionFactory
文件安全	backend/src/lib/fs-safe.mjs	resolveSafe, listDir, readTextFile, listAbsoluteDir
Git 操作	backend/src/lib/git.mjs	gitSummary, gitDiff, gitBranches, gitTree, gitBlob
Web 偏好	backend/src/lib/web-prefs.mjs	read/writeSessionPrefs, DEFAULT_WEB_PREFS
SSE 客户端	frontend-next/src/sse.ts	connectEvents（EventSource + 指数退避）
会话状态	frontend-next/src/store/SessionProvider.tsx	SessionProvider（~700行核心状态管理）
侧栏	frontend-next/src/components/Sidebar.tsx	NewSessionBtn（Canvas 粒子动画）, SessionRow
工程面板	frontend-next/src/components/Panel.tsx	FilesPane / GitPane / SkillsPane / ToolsPane / NotebookPane

3未来新功能规划

基于现有架构与使用场景，以下功能均可在前端 + 后端的现有扩展点上快速落地。工作量评估以「人·小时」为单位（假设 1 名熟悉技术栈的开发者）。

规划 1P0 免费模型额度本地统计

需求分析

当前 OpenRouter 免费模型（glm-5.3 / deepseek-v4-flash 等）用量无本地统计
用户无法预判免费额度何时耗尽，需手动到 OpenRouter 官网查看
目标：在面板内展示各模型已用 tokens / 剩余额度 / 周期重置时间

技术方案

数据源：OpenRouter Usage API（GET https://openrouter.ai/api/v1/usage，Bearer Key）
存储：/root/.pi/agent/usage.json，每日 cron 同步一次
后端：新增 /api/usage/sync（手动/自动）和 /api/usage（查询）路由
前端：侧栏顶栏 Badge 显示剩余额度，设置页展示历史图表（ECharts 已有依赖）
兼容：非 OpenRouter 模型显示 "额度不可用"

工作量评估

后端：约 4h（API 封装 + 路由 + 持久化 + cron 集成）
前端：约 4h（Badge + 图表 + 设置页集成）
合计：~8h（1 人·天）

规划 2P0 多 Key 轮换与额度查询

需求分析

DeepSeek / 智谱等 Provider 当前只配置单个 API Key
Key 过期或额度不足时无感知，请求失败后才发现问题
多 Key 场景（如团队共用）无法分摊用量

技术方案

存储扩展：auth.json 改为 {provider: [{key, label, enabled, lastUsed, error}]}
后端：/api/config/credentials 支持数组读写；新增 /api/config/key/rotate 轮换接口
Key 健康检查：/api/config/key/status 调用各 Provider 的 usage/health 端点
自动轮换：请求失败 401/429 时自动切换下一个可用 Key，记录轮换日志
前端：设置页多 Key 列表 + 轮换按钮 + 健康状态灯

工作量评估

后端：约 8h（存储改造 + 轮换逻辑 + 健康检查 + 自动降级）
前端：约 4h（Key 列表 + 状态 + 轮换交互）
合计：~12h（1.5 人·天）

规划 3P1 会话分享管理后台

需求分析

当前 /share/ 分享为纯静态 HTML，无管理后台
无法统计分享次数、查看分享列表、撤销已分享内容
目标：可查看/删除分享链接、查看访问统计

技术方案

存储：新增 /root/.pi/agent/shares.json，记录 { id, sessionFile, url, createdAt, views, title }
后端：GET /api/shares（列表）/ DELETE /api/shares/:id（撤销）/ POST /api/share/session（增强：登记到 shares.json）
前端：设置页增加「分享管理」Tab，列出已分享会话，可一键撤销
统计：可选——Nginx access log 分析 /share/ 路径访问量

工作量评估

后端：约 4h
前端：约 3h
合计：~7h

规划 4P1 移动端体验深度优化

需求分析

当前已有基础适配（左侧边栏、手势返回），但仍可优化
场景：通勤途中使用手机面板，处理轻量对话/查看代码状态
痛点：键盘弹出时输入框遮挡、消息气泡在窄屏换行差、工程面板操作不便

技术方案

虚拟键盘适配：监听 visualViewport resize，动态调整输入框位置
触摸优化：消息区域增大触摸热区（≥48px），滑动手势更多（左滑删除队列项）
离线缓存：Service Worker 缓存静态资源 + 最近会话状态（浅层离线可用）
PWA：添加 manifest.json，支持「添加到主屏幕」
工程面板简化：移动端隐藏 Git Diff 等重操作，保留文件浏览 + Skills

工作量评估

虚拟键盘 + 触摸优化：约 6h
PWA + 离线缓存：约 6h
面板简化 + 测试：约 4h
合计：~16h（2 人·天）

规划 5P2 更多模型源接入

需求分析

当前已支持 OpenAI 兼容（DeepSeek）+ Anthropic 兼容（智谱/ glm）
用户期望支持：Ollama 本地模型、Claude 官方 API、Google Gemini、Azure OpenAI 等
核心障碍：不同 API 的消息格式/工具调用/错误处理差异

技术方案

抽象层：利用 pi-coding-agent 已支持的 ModelRuntime 抽象，新增 provider 实现
Ollama：本地 http://host:11434，兼容 OpenAI 格式，几乎零改造
Claude 官方：需要转换消息格式（Anthropic 原生格式），适配 tool_use/tool_result
Gemini：需实现内容块转换（Pi 的 ContentBlock → Gemini parts）
配置 UI：在 /api/config/provider 中增加 provider 类型模板选择

工作量评估

Ollama：约 2h（基本即插即用）
Claude 官方：约 12h（消息格式/工具/认证全面适配）
Gemini：约 10h（内容格式差异较大）
配置 UI 改造：约 4h
合计（每家）：Ollama 2h / Claude 12h / Gemini 10h

规划 6P2 Agent 执行日志审计

需求分析

多用户/团队场景下需要追溯 agent 的操作行为（执行了哪些命令、修改了哪些文件）
当前日志分散在 journald 中，无结构化查询
目标：按会话/时间/工具类型检索 agent 操作记录

技术方案

日志格式：将工具执行事件统一为 JSONL 格式（tool name / args / result / duration / sessionFile）
存储：/root/.pi/agent/audit/YYYY-MM-DD.jsonl，每日滚动
后端：/api/audit 路由（按时间范围/会话/工具类型过滤）
前端：「审计」Tab，时间轴视图 + 工具类型筛选

工作量评估

后端：约 6h
前端：约 6h
合计：~12h

优先级汇总

优先级	功能	工作量	ROI 评估	建议
P0	免费模型额度统计	~8h	高（直接省钱）	立即执行
P0	多 Key 轮换与额度	~12h	高（可靠性保障）	立即执行
P1	会话分享管理后台	~7h	中（管理便利）	本周内
P1	移动端深度优化	~16h	中（用户体验）	下周安排
P2	更多模型源	2-12h/家	低（按需）	有需求时
P2	审计日志	~12h	中（合规）	团队有要求时

4附录

4.1关键文件清单

配置与数据

/opt/pi-web-plus/ 项目根目录（含 .git）
/opt/pi-web-plus/backend/src/ 后端源码
/opt/pi-web-plus/frontend-next/ 前端源码
/opt/pi-web-plus/frontend-next/dist/ 构建产物（nginx 托管）
/root/.pi/agent/ 数据目录（会话/models/auth/prefs/schedules）

系统服务

/etc/systemd/system/pi-web-plus.service 主服务
/etc/systemd/system/pi-web-plus.service.d/override.conf 密码覆盖
/etc/systemd/system/pi-web-plus.service.d/10-home.conf HOME 环境
/usr/local/bin/piweb-redeploy.sh 部署脚本（软链接）

Nginx 配置

/etc/nginx/conf.d/pi.haoaiganfan.top.conf 主站点
/etc/nginx/conf.d/docs.haoaiganfan.top.conf 文档站点
/etc/nginx/snippets/pi-web-plus-frontend.conf 前端共享片段
/etc/nginx/snippets/haoaiganfan-ssl.conf SSL 片段
/etc/nginx/snippets/errors.conf 错误页片段

运维命令

systemctl status pi-web-plus 查看状态
systemctl restart pi-web-plus 重启后端
journalctl -u pi-web-plus -f 实时日志
curl https://pi.haoaiganfan.top/api/health 健康检查
python3 /opt/pi-web-plus/tests/smoke.py 冒烟测试
piweb-redeploy.sh --build 全量重新部署

4.2API 速查

方法	路径	说明	鉴权
POST	/api/login	密码登录 → 返回 HMAC Token	无需
POST	/api/logout	退出登录	需要
GET	/api/health	健康检查（ok/name/build/slots）	无需
GET	/api/me	当前用户信息	需要
GET	/api/events	SSE 事件流（Long-Poll）	需要
GET	/api/sessions	会话列表 + 项目分组	需要
GET	/api/sessions/search?q=	全文搜索（grep 预过滤）	需要
POST	/api/new	新建会话	需要
POST	/api/switch	切换会话	需要
POST	/api/prompt	发送消息（支持图片）	需要
POST	/api/abort	中止当前回合	需要
GET	/api/state	会话状态（tail/full 模式）	需要
POST	/api/session/delete	软删除（归档）	需要
POST	/api/session/rename	重命名	需要
POST	/api/session/fork	分叉为新会话	需要
POST	/api/session/compact	压缩上下文	需要
POST	/api/session/export	导出 JSONL/HTML/MD	需要
POST	/api/share/session	生成分享链接	需要
GET	/api/models	可用模型列表	需要
POST	/api/model	切换模型	需要
GET	/api/config/models	模型配置（含脱敏凭证）	需要
POST	/api/config/provider	添加/更新 Provider	需要
POST	/api/config/credentials	保存/删除 API Key	需要
GET	/api/tools	工具列表 + 开关状态	需要
POST	/api/tools	设置活动工具	需要
GET/POST	/api/plan	Plan 模式开关	需要
GET/POST	/api/delivery	插话策略设置	需要
POST	/api/btw	/btw 临时侧问	需要
GET	/api/push/config	推送配置	需要
GET	/api/schedules	定时任务列表	需要
GET	/api/files	文件浏览（showHidden 开关）	需要
GET	/api/git	Git 状态/Diff/Branch	需要
GET	/api/skills	技能列表	需要
GET	/api/notebook	跨会话笔记本	需要

本文档基于对 pi.haoaiganfan.top 部署环境（2026-09-15）的系统性分析整理，涵盖系统架构、实现原理与功能规划。

服务器：110.40.142.210（OpenCloudOS）· 框架：pi-web-plus v0.1.0 · 构建日期：2026-09-15

文档地址：https://docs.haoaiganfan.top/ · 本地路径：/var/www/pi-docs/index.html