在 Linux 上 pi-web-ui server install 会落成一个 systemd unit，systemctl enable --now 之后实例开机自启、崩溃由 systemd 拉起。但守护不止这一个动作，server 子命令族才是日常：server status 看运行状态与实时统计（版本、PID、排空状态、已连接浏览器、运行中会话），server restart|stop|start 管生命周期，server uninstall 彻底移除，server shortcut 生成桌面快捷方式。所有配置在安装前都能预演：pi-web-ui server install --print 会把它将要写出的 unit 打印出来然后退出，先审再装。要改端口、cwd 或引擎不必手改 unit——重跑一次带新参数的 server install，它会重新生成并重启服务。容器里没有 systemd 时，靠的是镜像自带的崩溃退避与看门狗，别在容器里再套一层进程管理器。
quiesce 在升级与备份前的作用
升级前最怕「有会话正跑着就被打断」。server quiesce 会进入排空模式：拒绝新的对话、fork 与会话恢复，但已在跑的会话会跑完再收尾；处理干净后再 server unquiesce 重新放行。所以在重启服务、换版本、做备份之前，标准动作是 quiesce → 等在手的任务结束 → 操作 → unquiesce。
二、数据持久化：哪些东西不该随实例消失
数据到底落在哪两个目录
pi-web-ui 的状态分两处：会话记录在 /sessions/（默认 ~/.pi/agent/sessions/），UI 设置、最近项目、插件、上传、主题、语言包在 （默认 ~/.pi-web/）。这两个目录在卸载、升级、重装中都会保留——npm uninstall -g pi-web-ui 不会删掉任何会话；反过来，真要清干净也得手动删，而且删之前要先备份 sessions/ 与 plugins/。重装后跑一次 server install 就会重新接管。想换位置有两个开关：--data-dir 与 --agent-dir。
容器的数据边界
容器里数据目录 /app/.pi-web 是 volume，容器一重建，没挂卷的东西就全没了。用 compose 的具名卷 pi-web-data（或显式挂载）把它持久化；同时 PI_WEB_HOST=0.0.0.0 是端口映射的必需项，不设容器外连不上。上传文件默认按 PI_WEB_UPLOAD_RETENTION_DAYS（14 天）清理，设 0 表示永不清理；DSH 引擎的会话按 PI_WEB_DSH_SESSION_RETENTION_DAYS（90 天）清理。这两个保留期要和你自己的备份节奏对上。
三、访问控制与边界
三把访问控制的钥匙
第一把是 PI_WEB_TOKEN，四种带法（Authorization: Bearer、X-PI-Token、?token=、pi_web_token cookie），而 /api/health 保持开放给探针。第二把是 PI_WEB_ALLOW_HOSTS，在永远开启的同源校验之上再加一层主机名白名单。第三把是 PI_WEB_TABS，只暴露需要的标签页，服务端也会拒绝隐藏页的消息，chat 不可关。另外 PI_WEB_MANAGED=1 用于「由外部部署托管」的场景：它会明确拒绝自更新、装 pi CLI、装插件并在 UI 隐藏这些入口（版本 chip 变成纯文字），副作用是升级得你自己维护——所以要么把安装动作放进镜像构建阶段，要么干脆别开它。
文件与凭证的边界
内置文件接口的边界很明确：工作区相对读写会拒绝 .. 逃逸，工作区外的路径只能通过显式绝对路径访问；/api/file 的内联流只限图片、视频和 HTML，其它类型必须带 ?download=1 以附件形式下载，二进制没法藏在 Authorization / API key）永远留在服务端，不下发浏览器。
四、可观测与治理
看门狗与健康探针
工具有三道温和的兜底：单次工具调用超过 20 分钟自动中止（PI_WEB_TOOL_TIMEOUT_MS，Settings → Tools 可覆盖，0 关闭，问卷类调用豁免）；流式运行 3 分钟没有任何事件时给警告但不中止（PI_WEB_STALL_NOTIFY_MS）；终端静默 15 秒后提醒 AI 去看一眼（PI_WEB_TERMINAL_IDLE_MS）。外部探针直接打 /api/health 即可，它不需要令牌，也顺带暴露了当前解析到的 SDK 副本清单。
阿里云上的落位建议
实例层面，安全组按最小放通：对外只开必要的 80/443（或 SSH 的 22），服务端口不要对外暴露；数据目录放在数据盘上能与系统盘解耦，实例重装时更好搬迁。备份用快照与自制镜像，尤其在做大版本升级或改数据目录之前打一次。计费上按需选按量或包年包月，长期常驻更适合后者。网络方面留意 EIP 与带宽：反向代理和 WebSocket 长连接都会持续占用一点出网带宽，带宽偏小时长连接多开几路就容易挤。
需要一并说明的是，该插件在本站的静态安全扫描中被评为 🔴 高危（安装期即执行代码、命令参数由运行时变量拼接），目前没有任何人工复核。请把它当成一条待核实的提示，而不是安全承诺。
总结
云上跑 pi-web-ui 的重心是进程守护、数据持久化、访问控制与可观测这四件事，安装只是开场；
适合与不适合
适合：要长期常驻、希望实例重启后自动恢复的人；在意会话与上传数据可迁移、可备份的人；需要按人收敛可见标签页、把凭证留在服务端的人；用 docker compose 跑、需要明确定义数据边界的人。不适合：只临时用一次、不想维护常驻服务的人；没有备份与快照习惯、又不接受数据只在单机上的人；指望开箱即用零配置的团队。
标签：pi-web-ui、DeepSeek Harness、进程守护、数据持久化
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
