Pi Web

English | 简体中文

本项目是基于 @agegr/pi-web 的增强分支，为 Pi 编程智能体 提供本地及远程 Web 操作界面，内置了基于 Session Cookie 的 Web 登录页面、时序安全鉴权与注销支持。

---

本分支新增特性

相比原版，本分支主要增加了以下功能：

1. 专用 Web 登录页面 (/login)：
   • 替代浏览器原生的 HTTP Basic Auth 弹窗；
   • 纯密码输入设计，回车即可登录；
   • 支持暗色/亮色主题与多语言切换（简中、繁中、英文）。
2. Session Cookie 鉴权与向下兼容：
   • 采用 HMAC-SHA256 签名的 HttpOnly Session Cookie 进行会话状态保持；
   • 保留对 Authorization: Basic 请求头的支持，便于 API 和脚本调用；
   • 密码与 Token 比对均使用 crypto.timingSafeEqual 防范时序侧信道攻击；
   • 内置防开放重定向（Open Redirect）校验。
3. 顶栏注销入口：
   • 在顶部语言/设置菜单中常驻退出登录选项，点击后清除 Cookie 并返回登录页。

---

安装与运行

1. 从源码安装并全局使用（推荐）

git clone https://github.com/ligonfei/pi-web.git
cd pi-web
npm install
npm run build
npm install -g .

安装完成后，在终端直接运行：

pi-web

2. 源码开发模式

cd pi-web
npm install
npm run dev

本地开发服务默认启动在 http://127.0.0.1:30141。

---

配置说明

支持通过命令行参数或环境变量进行配置。命令行参数优先级高于环境变量。

参数与环境变量对照表

命令行参数	环境变量	说明	默认值
-p <端口>, --port <端口>	PORT	监听端口	30141
-H <主机>, --hostname <主机>	PI_WEB_HOSTNAME	监听主机地址	127.0.0.1
--no-open	PI_WEB_NO_OPEN=1	启动后不自动在本地打开浏览器	自动打开
—	PI_WEB_PASSWORD	访问密码。设置后启用 Web 登录与 Basic Auth 鉴权	未设置（不鉴权）
—	PI_WEB_ALLOWED_HOSTS	允许的主机名白名单（通过反向代理访问时需要配置，逗号分隔）	未设置
—	PI_CODING_AGENT_DIR	自定义 Pi Agent 数据目录	~/.pi/agent

启动示例

# 1. 本地免密启动（不自动打开浏览器）
pi-web --no-open

# 2. 指定端口并设置访问密码
PI_WEB_PASSWORD="your-strong-password" pi-web -p 30141 --no-open

# 3. 局域网/服务器部署（监听所有网卡）
PI_WEB_PASSWORD="your-strong-password" PI_WEB_ALLOWED_HOSTS="pi.example.com" pi-web -H 0.0.0.0 -p 30141 --no-open

---

systemd 后台服务配置（Linux）

在 Linux 服务器上，可以通过 systemd 保持服务常驻后台运行：

创建配置文件 /etc/systemd/system/pi-web.service：

[Unit]
Description=Pi Web UI Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root
Environment=NODE_ENV=production
Environment=PATH=/root/.local/share/pi-node/node-v22.23.2-linux-x64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
Environment=PI_WEB_PASSWORD=your-strong-password
Environment=PI_WEB_ALLOWED_HOSTS=pi.example.com
ExecStart=/usr/local/bin/pi-web --no-open -H 127.0.0.1 -p 30141
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target

常用管理命令：

systemctl daemon-reload
systemctl enable pi-web
systemctl start pi-web
systemctl status pi-web

---

测试与代码检查

# 运行单元测试（覆盖鉴权、会话、路由、多语言等）
npm test

# 代码风格与语法检查
npm run lint

# TypeScript 类型检查
node_modules/.bin/tsc --noEmit

---

项目目录说明

app/             Next.js App Router 页面、布局与 API 路由
  ├── api/auth/web/  Web 登录、登出与会话检查接口
  └── login/         登录页面
components/      UI 组件（包含 AppShell 导航框架、模型与会话管理等）
hooks/           React 自定义 Hooks
lib/             核心逻辑（web-auth 鉴权、i18n 多语言、会话管理、Git 交互）
proxy.ts         Next.js 中间件（负责安全拦截、鉴权分流与防重定向校验）
bin/             npm CLI 命令行入口脚本
public/          静态资源与 PWA 清单

---

致谢名单

本项目在开发与演进过程中，参考并使用了以下开源项目与社区贡献，在此深表谢意：

• @agegr/pi-web：Pi Web 原项目，提供了完整的 Web 架构、交互逻辑与界面实现。
• @earendil-works/pi：底层的 Pi 编程智能体生态。
• Next.js & React：底层 Web 应用与组件渲染框架。

---

许可证

MIT