项目手册 · Saki Panel

01 WHAT IT IS

这是什么

Saki Panel 是一个开源自托管的服务器运维面板。它要解决的问题很具体：看日志、改配置、起停服务、翻 Git 差异、盯资源占用，这些平时要开五六个终端窗口的事，收进一个浏览器页面，并在页面右侧常驻一个能直接动手的 AI 助手。

它管的东西比较杂。本地进程、Docker 容器、Docker Compose 编排、Minecraft 服务端、Steam 游戏服务器、远程 Linux 机器上的服务，都作为"实例"接入，用同一套界面操作。游戏服开服的人、手上有几台 VPS 的独立开发者、想给团队搭一个内部运维台的人，是它主要面向的使用者。

和常见的运维面板相比，它的差别主要在两个功能。一是 Saki 助手：接入本地或云端大模型的对话入口，能读实例的实时日志、打开配置文件、给出补丁并直接写到磁盘上，而不是只回一句"你可以试试重启"。二是 Saki Watch：一组常驻的故障检测器，服务崩了会自动诊断、申请补丁审批、重启验证，失败还能回滚。第十章"实验与验证"里有这两部分的实测数据。

整套代码以 Apache 2.0 许可发布，数据库是单文件 SQLite，凭据加密后存在你自己的 data/ 目录里。没有云端控制面，断网也能正常使用，唯一的外部依赖是你自己选的模型服务。

02 ARCHITECTURE

架构与仓库

面板跑起来是三个进程，各占一个端口，职责分开：

三者之间的通信方式决定了故障时的表现，值得留意。Web 与 Panel 之间走普通 HTTP，另加两条特殊通道：WebSocket 用于终端的实时输入输出，SSE 用于 Saki 的流式回复。Panel 与 Daemon 之间是带鉴权的 HTTP/WS：Daemon 主动向 Panel 注册，之后每 10 秒心跳一次，所以面板能区分"服务挂了"和"整台机器掉线"两种不同的事故。

仓库是 npm workspaces 的单仓结构：

apps/web        前端（视图、组件、i18n、路由）
apps/panel      API 服务（routes、watch、saki、points、mcp-host）
apps/daemon     节点执行器（进程管理、指标上报）
packages/shared @webops/shared —— 三方共用的协议层：43 个权限码、
                实例类型枚举、命令安全策略、事件定义
prisma/         schema.prisma，23 个模型，SQLite 落在 data/panel/dev.db
docs/           审计报告、案例复现、研究资料
official-website/  官网与这一页
operations-packs/  在线运维包（含 SHA-256 校验清单）

把协议和命令安全策略放进 packages/shared 是有意为之：前端的权限门控、Panel 的接口校验、Daemon 的命令放行，三处必须引用同一份定义，任何一方单方面放宽都会留下空子。新增实例类型或权限码时，第一步永远是改 shared，这个约定写在 CONTRIBUTING 里。

数据库那 23 个模型里，和日常使用关系最大的几组是：Instance（实例，含重启策略与重试上限）、Node（节点）、InstanceAssignment（把实例分配给用户，并附带该实例的权限子集）、WatchPolicy / Incident（Watch 的策略与事件）、OperationLog（审计流水）、PointRecord（积分流水，每笔都记余额快照）、SakiConversation（会话与上下文归组）。

03 GET IT RUNNING

把它跑起来

从源码跑是最省事的路径，三个进程一条命令全起。前提是 Node.js ≥ 22.13、npm ≥ 9：

git clone https://github.com/EthanChan050430/Saki-Panel.git
cd Saki-Panel
npm install
npx prisma db push
npm run dev

起完打开 http://localhost:5478，默认账号 admin / admin123456。第一次登录后先改密码，并把 .env 里的 JWT_SECRET 换成随机值。这两项必须改：面板暴露到公网后出事的，基本都是这两项没动。

.env.example 把可调项都列了出来，常用的几组是：

生产部署有三条现成路线。Docker Compose 拉 docker-compose.ghcr.yml，先把三个密钥填好再 up -d；发行包从 Releases 下载，Windows 的 zip 解压即跑（自带 Node 运行时），Linux 的 tar.gz 要求机器上有 Node 22.13+；源码方式则配合你自己的进程管理器。升级前先停服务、备份 data/ 和 .env，数据库结构在启动时自动同步。

公网部署绕不开 HTTPS，有两条路。省事的一条用面板内置的能力：把 fullchain.pem 与 privkey.pem 放进仓库的 ssl/ 目录（可选 ca_bundle.pem），Panel、Daemon 与 Web 会在原端口直接用 HTTPS 起服务，不必再架一层反代。另一条是反向代理：由 nginx 或 Caddy 终结 TLS，再转发给本机端口。配反代有两处容易踩空：转发规则要放行 WebSocket 的升级头并关掉响应缓冲，否则终端会黑屏、Saki 的流式回复会退化成一次性整段刷出；TRUST_PROXY 只在面板确实位于可信代理之后时才设为 1——这个开关信任 X-Forwarded-For，开得不对等于把登录限流交给客户端伪造。

location / {
    proxy_pass http://127.0.0.1:5478;   # Panel API 的 5479 同理
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;   # 终端 WebSocket 必需
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_buffering off;                      # SSE 流式回复必需
}

部署完成后的小毛病，大多有固定的排查顺序。节点显示离线：Daemon 每 10 秒心跳一次，面板才能区分"服务挂了"和"整机掉线"；节点一直离线时，先查 Daemon 侧 DAEMON_PANEL_URL 与 DAEMON_PUBLIC_HOST 是否指得对面板，再查 5480 端口在网络上可达。终端黑屏、或 Saki 的回复不再逐字流出：九成是反代掐了 WebSocket 升级头或缓冲了 SSE，配置见上一段。浏览器控制台报 CORS：把实际访问来源填进 WEB_ORIGIN 或 PANEL_CORS_ORIGINS。面板跑在 Docker 里却连不上 Ollama：localhost:11434 指的是容器自己，要填宿主机在容器网络中可达的地址。想看面板与 Daemon 的详细请求日志，把 LOG_LEVEL 从默认的 warn 调到 info 或 debug。概念性的常见问题——它是什么、AI 是否安全、收不收费——在官网首页的问答区。

04 UPGRADE & BACKUP

升级与备份

装好之后，两件迟早要做的事是想清楚怎么升级、怎么备份。好消息是面板的全部状态都在两处：data/ 目录和 .env。SQLite 是单文件库（data/panel/dev.db），节点凭据、实例配置、审计流水、Watch 事件都在里面；密钥、管理员密码、Daemon 注册令牌在 .env 里。把这两处带走，面板就完整搬了家。

从源码升级的路径是：停掉三个进程，git pull 取回新版本，npm install 补上可能新增的依赖，再 npm run db:push 让 Prisma 把数据库 schema 推到新版本（这条命令会先运行 scripts/prepare-db.mjs 再执行 push），最后重新启动。Docker 部署更简单：docker compose pull && docker compose up -d，环境变量保持不变。跨版本升级之前，先看该版发行说明里有没有破坏性变更，再动手。

备份最稳的方式是停机复制：面板与 Daemon 都停掉之后，整个 data/ 目录连同 .env 一起拷走。想在面板运行中备份 SQLite，不要直接复制 dev.db 文件——可能拷到写了一半的页，用 sqlite3 data/panel/dev.db ".backup 目标文件" 导出才安全。还有一样东西不在数据库里：实例工作目录。游戏存档、世界数据、用户上传的文件都存在创建实例时指定的目录中，面板库里只记路径，备份时记得把它们一并纳入。

恢复就是反向操作：停服，放回 data/ 与 .env，启动。集群里的节点若显示离线，在节点管理里按注册流程重新接入，注册令牌就在 .env 的 DAEMON_REGISTRATION_TOKEN 里。最后提醒一句：Saki Watch 的回滚检查点不是备份。v5.1 起同机跨工作区命令会带文件检查点，验证不通过便退回改动，它解决的是"改错了"，不是"盘坏了"；检查点存在面板环境里，只有随 data/ 一起备份才真正留得住。

05 THE WORKSPACE

功能全景

侧边栏把面板切成十个视图，路由是 hash 形式（#/instances、#/settings/watch），刷新不丢位置，也方便把某个实例的链接直接发给同事。下面逐个说每个视图能做什么。

概览

打开面板的第一屏。汇总所有节点的 CPU、内存、磁盘、网络曲线，实例的运行状态分布，以及最近的事件流。Watch 触发的事故会在这里冒头，顶栏的铃铛（Incident 收件箱）是它的快捷入口。

实例

面板的心脏。一个实例 = 一种可被启停管理的服务单元，九种类型共用同一套详情页：概览、终端、日志、文件、Git、数据库、任务。终端是带 xterm 的浏览器 shell，日志实时推送，文件管理器支持往里拖文件，也支持把文件直接丢给 Saki 分析。右上角常驻 Saki 聊天，能看到当前实例的上下文。

节点

管理两类接入对象：跑着 Daemon 的托管节点，以及 SSH 免装直连的远程机器。节点详情里能看到心跳状态、实时指标、已部署的实例。掉线会明确标出来，心跳超时与服务崩溃在事件里是两回事。

模板

把一套实例配置（类型、启动命令、工作目录、重启策略、环境变量）存成模板，新建实例时套用。开服的人常用它维护"纯净原版""插件服"几套预设。

用户与角色

多用户体系的管理处：建账号、分角色、给角色勾权限码，以及把具体实例分配给具体的人。分配实例时还能在该实例上再收窄一层权限：同一个人在 A 服能执行命令，在 B 服可能只能看日志。用户积分（Saki 的计费单位）也在这里充值和查看流水。

审计

OperationLog 的查询界面。谁、在什么时候、对哪个对象、做了什么，全部落库。命令类操作会记下被安全策略拦截的尝试，这是事后追责的依据。

可靠性

Watch 事件（Incident）的集中视图：每条事故的指纹、诊断过程、补丁内容、审批记录、重启验证结果和回滚点都串在一条时间线上。第七章展开讲。

设置

七个分区：system 基础信息、model 模型接入、features 功能开关、appearance 主题外观、prompt 提示词定制、skills 技能管理、watch 故障响应策略。Saki 的默认权限模式、积分倍率、Watch 的自动诊断开关都在这里定。

插件

插件工坊的客户端，从 github.com/EthanChan050430/saki-plugins 拉取插件列表，装上后可以换皮肤、加组件。插件卡片是整图沉浸式布局，更新有角标。

关于

版本信息、仓库链接、更新日志入口，外加一个左侧目录跟随滚动的介绍页。

另有两个贯穿全局的快捷功能：Ctrl/Cmd + K 唤起 Spotlight 命令面板，模糊搜索实例、视图与常用操作；文件可以在 Saki 面板与文件管理器之间拖拽中转，聊天里提到的文件点一下就定位。所有视图入口都按权限码门控：没有对应权限的菜单项直接不渲染，而不是渲染后点了才报错。

06 INSTANCES & NODES

实例与节点

九种实例类型决定了面板"会管什么"：

每个实例都能配重启策略，四种：never（崩了不自动拉起）、on_failure（非零退出才拉起）、always、fixed_interval（按固定间隔重启）。同时有 restartMaxRetries 控制连续重试上限，避免一个必然起不来的服务无限消耗机器。做 Watch 实验时通常把策略设成 never，否则服务自己重启了，观察不到完整的事故流程。

接入远程机器的两条路

SSH 免装直连。填主机、端口、密码或私钥，加密后存进 data/panel/ssh-nodes，立刻获得 Web 终端、系统指标浏览、命令执行。适合"上去敲个命令看看"的轻量场景，对面机器零改动。

创建托管组件。在目标机上跑起 Daemon（面板提供安装命令，落到 ~/.saki-panel/nodes/<id>），从此这台机器能被完整托管：实例的创建、启停、日志、监控、Watch 全套生效。Daemon 只监听回环地址，与 Panel 之间靠注册令牌换来的节点令牌鉴权，暴露面只在面板一侧。

还有一层容易忽略的设定：多工作区。一台机器上可以同时挂最多 8 个 Saki 工作区（maxSakiWorkspaces），SSH 节点会以 node:{id} 的合成实例身份出现在工作区列表里。这让"同一个面板同时管本机和多台远程机的 AI 上下文"成为可能，第五章提到的跨工作区命令在 v5.1 里专门修过文件检查点的问题。

健康检查

实例可以配 HTTP 健康端点，返回 2xx/3xx 即视为健康。它是 Watch 验证环节的裁判：补丁打完、服务重启后，靠连续的健康检查结果判定"这次修复成没成"。配置不当的健康检查不会让流程崩溃：验证逻辑对异常一律按不健康处理，不会抛错中断整个响应链。

07 SAKI ASSISTANT

Saki 助手

Saki 是面板内嵌的 AI 助手，也是权限边界最需要说清的部分。它不只是聊天窗口，一共挂了 65 个工具（含别名），大致分五类：

• 读 —— readFile、searchFiles、findFiles、gitStatus、describeInstance、listInstances，把实例状态、文件内容、仓库差异拿进上下文；
• 写 —— writeFile、replaceInFile、editLines、applyPatch，改配置、打补丁，文件改动按会话跟踪；
• 动手 —— runCommand、runServerCommand、instanceAction（启停重启实例），真正触碰你的服务；
• 向外 —— searchWeb、browse、crawl、researchSkills、generateImage，查资料、读网页、生成图；
• 协作 —— askUser（停下来问你）、spawnTask（派子任务）、readMemory（读长期记忆）、requestExternalAccess（申请一次性的外部访问）。

回复走 SSE 流式，帧类型依次是 meta / heartbeat / workflow / delta / thinking / action / done / error。界面上看到的"思考中""正在调用工具""执行动作"这些状态条，就是这些帧的直接映射。模型请求中断会自动重试，最多三次，且不丢已经完成的任务进度（v5.1 改进）。

四种权限模式

权限模式之外还有一层独立的终端沙箱开关：即使在放行模式下，命令仍要过共享层的命令安全策略（第 9 章）。两层是叠加关系，不是二选一。

模型接入

三类提供方：Ollama / LM Studio 本地推理（日志不发外网）、NVIDIA、以及一切兼容 OpenAI 协议的云端 API，GitHub Copilot 的原生工具与认证也接了。设置里的 model 分区管理具体配置，聊天窗口右下角能随时切换当前会话用哪个模型。这个下拉直接渲染在页面根节点上，不会被输入面板挡住。

Skills、MCP 与多工作区

常用排障步骤可以沉淀成 Skills 存起来，Saki 通过 researchSkills/readSkill 检索复用；外部工具经 MCP（模型上下文协议）接入，mcp-host 负责拉起子进程、暴露工具与资源；工作区最多 8 个，Saki 的记忆与上下文按工作区隔离，会话按 contextKey 归组。

积分：Saki 的计费单位

Saki 的每次调用都消耗积分，换算规则是：1000 Tokens = 1 积分，再乘以模型倍率，向上取整。倍率在设置里按模型配置，账单明细在"积分用量"弹窗里逐笔可查（PointRecord 带余额快照）。余额不足时接口返回 402，提示"积分不足，无法使用 Saki"，主流程不崩。管理员可以给用户开无限额度。

输入侧的限制

附件与外部读取有硬性上限：单次外部内容读取不超过 1 MiB、不超过 2000 行，超出即截断。这是防止一个网页或大文件把上下文撑满的保险丝，也是资源安全审计里明确要求的边界。

08 SAKI WATCH

Saki Watch：故障之后发生的事

Watch 是项目里自动化程度最高的部分。它常驻监听实例事件，判定故障后走一条五步流水线：

• 错误指纹 —— 对崩溃输出做归一化取指纹，同源事故去重（2 分钟内重复心跳崩溃不重复立案）；
• 诊断 —— Saki 读日志与相关文件，给出根因判断和置信度；
• 补丁审批 —— 生成的修复补丁推到可靠性页面等你确认，自动批准级别可配；
• 重启验证 —— 打补丁、重启、按健康检查等待判定（默认等 20 秒，检查超时 5 秒）；
• 回滚检查点 —— 验证不过，改动回退到检查点，事故升级到人工。

默认策略是一套保守参数，写在 watch/policy.ts：

检测器盯着什么

崩溃循环：10 分钟窗口内崩 3 次即判定，之后进入冷却。磁盘：占用过 90% 报警，回落到 80% 才解除，留 10 个点的回滞，防止在阈值附近反复横跳刷屏。内存同理，95% 报、85% 解。心跳：连续 2 次未达阈值判定失联。所有事件都有去重窗口。

通知往哪发

四个渠道原生支持：通用 webhook、钉钉、企业微信、Telegram；触发器覆盖 crash、crash_loop、disk、memory、webhook、health。已经在用 Prometheus 的团队可以直接把 Alertmanager 接进来，用现成的告警规则驱动通知。

三张截图连起来就是一次完整的自愈：事故立案、等待人工确认的修复补丁、重启后健康检查连续通过的恢复记录。这条链路在下一章有真实跑出来的数字。

09 PERMISSIONS

权限模型

权限的定义只有一份，在 packages/shared 里：43 个权限码组成 PermissionCode 类型，前端的菜单渲染、Panel 的接口鉴权、Daemon 的动作放行全部引用它。新增权限如果没进这份定义，等于没加。

结构是三层叠加的：

• 角色 → 权限码 —— 角色与权限多对多，面板预置了无权限的默认角色（noRolePermissionRoleName），新建用户从最小权限起步；
• 实例分配 —— InstanceAssignment 记录"谁能碰哪个实例"，并携带 permissionsJson 在该实例上进一步收窄，做到同人不同服不同权；
• 请求期校验 —— 接口按权限码校验，前端的 AccessEmptyView 兜底展示"无权访问"，而不是白屏。

Saki 的工具调用不走角色，而走风险分级审批（详见 docs/agent-permissions.md）：读取类动作按模式放行，命令与写入类按权限模式和命令策略双重把关，外部访问必须通过 requestExternalAccess 单次申请。审计文档（2026-10-25 那次权限审计）还把命令规则统一挪进了 shared、补上了敏感路径策略，这些改动的回归验证方式见第 10 章。

10 SECURITY

安全边界

这一章把散在各处的安全机制汇总起来，说明面板被攻破后的影响能限制在什么范围：

• 命令安全策略 —— 定义在 packages/shared/command-policy，所有经面板、Saki、Watch 发出的命令统一过筛，命中的直接拒绝并返回 Command was blocked by the panel safety policy，同时写审计。权限模式设成 bypass 也绕不过它。
• 敏感路径策略 —— 文件读写对系统关键路径设防，Saki 不能顺手把 /etc 或面板自己的数据目录改了。
• 外部访问单次授权 —— 浏览、抓取、联网检索都要先 requestExternalAccess，一次授权对应一次访问，不给长期通行证；单次读取上限 1 MiB / 2000 行。
• 凭据处理 —— SSH 私钥与密码加密落盘在 data/panel/，Daemon 用注册令牌换节点令牌，心跳与命令通道均带 x-node-id + x-panel-token 鉴权；Daemon 仅监听回环。
• 审计 —— OperationLog 全量记录，含被拦截的尝试；敏感操作在 UI 上对应权限码门控。
• 运维包纪律 —— operations-packs 从在线源下载时只做 SHA-256 校验，下载永不执行，脚本要跑由你看过再跑。

仓库根目录有 SECURITY.md 说明漏洞反馈渠道。账号边界、单次外部读取、命令规则三块的完整审计报告都在 docs/ 里，第 11 章列了清单。

11 EXPERIMENTS

实验与验证

这一章回答"你说的这些，我怎么自己验证"。分两层：跑测试，和复现一次完整的故障自愈。

自动化测试与 CI

仓库的测试入口是 npm run test:watch，覆盖 Watch 的审批决策与提示词生成两组逻辑（watch-approval 三个用例、watch-prompt 两个用例，共 5 例）。改动前先跑静态检查：

npm run check        # 类型检查与代码规范
npm run test:watch   # Watch 审批与提示词测试
npm run build        # 生产构建

CI 配置在 .github/workflows/check.yml：每次 push 与 PR 在 Node 20 上执行 npm ci → npm run check → npm run test:watch。提交 PR 前本地把这三步跑绿，是 CONTRIBUTING 里唯一强制的门禁；涉及 Agent、Watch、Daemon 安全路径的改动，额外要求补测试或在描述里写清验证方式。需要提醒的是，个别历史文档里提到过 verify:operation-packs、test:permissions 这样的脚本名，但 package.json 里并未定义，以仓库实际脚本为准。

案例复现：一次真实的端口占用自愈

docs/case-studies/port-recovery 记录了 2026-10-23 的一次实测：一个 Node 服务启动时端口被占，Saki Watch 走完全流程把它救了回来。当时的数据是这样的：

复现材料在 docs/examples/port-recovery，一个故意把端口写错（70000）的示例服务，健康端点在 http://127.0.0.1:16541/health。完整复现步骤：

1. 准备示例服务

   把 docs/examples/port-recovery 复制到面板能访问的工作目录。里面的 service.json 故意带着错误端口，这就是待修复的"故障"。

2. 配好模型与积分

   在设置里接一个可用的模型（实测用的是 Ollama 的 huihui_ai/qwen3-abliterated:latest），并给当前账号留足 Saki 积分，诊断阶段会消耗模型调用。

3. 建实例

   新建 nodejs 类型实例，启动命令 node server.mjs，重启策略选 never。策略必须是 never，否则服务崩溃后立即被拉起，Watch 就观察不到完整的崩溃事件。

4. 配置 Watch

   设置 → watch 分区：打开"诊断与补丁"，关闭"自动诊断"和"自动批准"（这样每步都人工可观察），验证等待改成 10 秒便于快速看到结果。

5. 触发并审批

   启动实例让它崩（端口占用会立刻退出），到可靠性页面从该事件发起诊断，审阅 Saki 给出的补丁——它会把端口从 70000 改成 16541——然后批准。

6. 验证恢复

   Watch 重启服务并做健康检查；终端里再跑 node verify-health.mjs，连续三次拿到 HTTP 200 即判定复现成功。

12 DOCUMENTATION

文档索引

仓库的 docs/ 目录比 README 深得多，多数是审计与研究记录。按需取用：

遇到文档没覆盖的问题，Bug 与新功能想法走 GitHub Issues（仓库自带模板）；安全相关的发现按 SECURITY.md 的私密渠道反馈，不要公开提 issue。

13 RELEASES

版本与许可

当前最新为 5.1。两个大版本各自补了什么：

发行包附 SHA256SUMS 校验文件，下载后先验 hash。Windows 包自带运行时，解压即用；Linux 包需要 Node 22.13+，解压后 npm ci → ./saki-panel。每次发布都记录了验证范围：5.1 写了"生产构建与 Watch 测试通过，Windows 包通过全新建库、启动、登录、资源加载、概览与节点列表检查"；5.0 则注明 Linux 启动器为交叉编译、未做运行时测试。

平台支持的范围一次说清：

项目采用 Apache License 2.0，商用、修改、分发都允许，保留许可证与版权声明即可。安全问题按 SECURITY.md 的渠道反馈，不要公开提 issue。