KPanel 产品质量与验收标准

August 24, 2026 · View on GitHub

  • 版本：2026-08-11
  • 状态：长期强制规范

本规范服从仓库根目录的 PROJECT_RULES.md，适用于 KPanel 的设计、 开发、代码评审、测试和发布。历史实现或文档与本规范冲突时，新改动必须按本规范收敛。 界面与视觉语言、字号层级、主题和可读性以 ui-visual-language.md 为产品设计入口； 本文件负责质量目标和验收分级，不复制另一套视觉数字。

1. 范围与解释

本规范中的“安全性”专指抵御来自网络、恶意请求、被篡改依赖和被攻陷上游服务的攻击，包括：

  • 未授权访问、撞库、Session 劫持和跨站请求；
  • 命令注入、路径穿越、SSRF、Host Header/代理头伪造和请求走私；
  • 凭据泄露、供应链篡改、容器逃逸和宿主机提权；
  • 利用超大输入、无限并发、慢连接、日志或任务耗尽 CPU、内存、FD、PID、磁盘和连接。

以下内容不属于安全控制，不能作为安全改进：

  • 因资源不是 KPanel 创建而禁止管理员管理；
  • 因操作危险、会卸载或会改变系统而隐藏按钮、禁用 API；
  • 用固定确认词、所有权标签或 KPanel 自保护代替真实鉴权；
  • 以“为了安全”为理由不实现 kejilion.sh 已支持的功能。

已经通过身份验证的管理员仍应获得底层业务实际支持的完整能力。防入侵措施必须约束攻击入口、 协议、输入、权限、供应链和资源消耗，不能缩减合法业务范围。

1.1 项目性质与质量推导

KPanel 的质量模型由实际产品形态决定，不直接照搬普通 Web 后台或大型多租户平台标准：

  1. 宿主机控制面：Panel 面向公网但无特权运行，Agent 是唯一宿主机高权限入口；一次错误写入 可能影响网站、容器、网络或登录能力，因此写路径比展示路径需要更强的失败和恢复证据。
  2. 生态同源：kejilion.sh、Docker Engine、Nginx、systemd 和实际文件是业务真源；KPanel 的 核心价值是让脚本、SSH、Compose 与 Web 对同一资源继续管理，而不是建立第二套面板事实。
  3. 轻量单管理员产品：目标包含低配 Linux 主机、amd64/arm64 和多种 systemd 发行版； 资源预算、响应速度和无需额外常驻服务本身就是产品能力。
  4. 后台运维工作台：安装、更新、备份、终端和体检可能跨页面、跨网络抖动、跨 Panel/Agent 重启持续运行；用户体验必须包含真实进度、可恢复状态和明确的部分失败，而不只是页面美观。
  5. 快速演进的 0.x 产品：允许小步高频交付，但每个版本必须保持范围聚焦、候选冻结、产物可追溯 和回滚可执行；发布速度与稳定性用数据共同判断，不通过人为等待或单纯发布次数判断。

当前项目性质、业务规模和发布节奏入口见 product-quality-review-current.md，历史日期文件只证明对应时点。 scripts/check-business-context-freshness.mjs 在基线后达到 50 个提交，或同时达到 20 个提交和 8 个正式 版本时要求刷新该入口；版本数量不能单独触发门禁。 产品性质、业务真源、权限边界或核心旅程实质变化时不等待数量门槛。刷新业务事实不自动提高验收等级， 也不以发布次数单独推断质量下降。

2. 质量目标

每项改动按影响范围满足六个目标：

  1. 业务真实且互通：状态来自真实资源，脚本/Web 双向继续管理，成功结论有产物复核。
  2. 性能可预测：常用读取链路无无界工作量，关键延迟和吞吐无不可解释退化。
  3. 稳定可恢复：页面关闭、网络抖动、Agent 重启或脚本失败后，任务状态和真实资源可恢复。
  4. 资源有上限：请求、响应、缓存、并发、日志、归档、FD、PID、CPU 和内存均有明确边界。
  5. 抵御网络入侵：公网请求不能越过 Panel、Agent、Docker 和宿主机之间的信任边界。
  6. 体验清晰可操作：桌面和移动端能完成受影响旅程，键盘焦点、反馈、错误恢复和多语言不退化。

“测试通过”必须有可重复命令或实机证据；不得仅凭代码阅读、进程退出码、systemd Result=success 或页面提示判定。

2.1 证据状态和层级

每个质量维度只能使用以下状态，禁止把实现、计划或历史版本结果写成当前已验证：

状态含义
已验证当前精确提交/产物在声明环境完成可复现检查，有命令、原始结果或链接
已实现未实机验证代码和自动测试存在，但缺少目标 Linux、真实脚本、真实浏览器或真实资源闭环
未实现底层适配器或产品能力不存在，必须明确缺口，不得包装为安全限制
不适用该发布画像没有触及此维度，并写明文件、契约或数据均未变化的依据

证据按用途分层，不能相互冒充：自动测试证明可重复逻辑；隔离真机证明宿主机、脚本和浏览器闭环； 公开产物 E2E 证明用户实际下载的镜像；生产部署安全核对只证明本次部署现场，不是新增质量验证证据。 危险、付费、耗流量或破坏性动作在隔离真机完成，生产未执行时如实记录，不要求为形式完整制造风险。 prod-108/108 禁用全部 KPanel 操作；测试、只读检查、备份、部署、升级和安全核对均不得连接。 发布验证与唯一正式部署默认都在 arena-154 完成。

本地或远程长时间浏览器测试通过 background-browser-validation 后台运行并持久化终态。普通确定性 交互不机械执行 soak；生命周期、重连、并发或资源趋势按风险选择明确窗口/循环数，后台化不减少断言。

面向用户的本地功能预览执行 docs/local-feature-preview-standard.md：每个会话交付预览等级、数据模式、 精确候选、动态回环地址、体验步骤、未验证边界、证据目录和停止方式。UI Mock 不能证明真实接口，回环 集成不能证明隔离发行版或公开产物；只有 clean checkpoint 可以形成验收级预览证据。

2.2 核心用户旅程

发布不需要无差别重跑所有页面，但必须识别并覆盖受影响旅程：

旅程不可破坏的产品契约
初始化与登录Bootstrap、登录/注销、Session、CSRF、2FA/恢复入口和错误反馈可用
总览与系统管理读取真实主机状态；Agent 离线明确降级；系统写入复用固定脚本协议并可回读
网站、环境与应用kejilion.sh/Web 双向发现和继续管理；后台任务、终端、失败清理可恢复
Docker 与文件外部资源仍可管理；路径、归档、资源版本和大数据量边界不退化
终端、体检与长任务输入区、焦点、ANSI、断线重连、页面关闭和重启后的进度连续性可用
集群与轻量节点本机不依赖远端；配对、撤销、协议版本、Noise/HTTPS 和离线状态明确
AI 运维助手Provider/模型兼容，工具只调用固定 KPanel 能力，写操作确认和恢复语义明确
全局交互桌面/移动端、浅色/深色、键盘、缩放、多语言和无横向溢出按受影响范围验证

3. 固定信任边界

Internet
   |
   v
k fd / HTTPS reverse proxy
   |
   v
paneld (unprivileged container)
   |
   v
Unix Socket + independent token
   |
   v
kejilion-agent (host service)
   |
   +--> kejilion.sh / systemd / filesystem
   +--> local Docker Unix Socket
边界强制要求
Internet → 反向代理HTTPS；Host 和客户端地址只由明确配置的代理产生；公网来源不得伪造转发头
反向代理 → Panel只信任最小 CIDR；X-Forwarded-Proto 必须是单一 https；k fd 域名反代必须持续兼容
浏览器 → Panel API身份、Session、CSRF/Origin、方法、Content-Type、请求体和速率均验证
Panel → Agent仅 Unix Socket；独立 Bearer Token；Panel 不挂载 Docker Socket、不获得宿主机特权
Agent → 宿主机固定动作枚举、结构化参数、固定业务根；不接受由 Web 字段拼出的任意 Shell
交互终端 → 脚本只能连接已登记的脚本任务和 PTY；输入有长度上限，任务仍执行脚本原生交互语义
供应链 → 运行时镜像、脚本、Action 和工具固定版本或摘要；下载有大小、超时和完整性校验

新增网络入口、监听端口、代理 CIDR、外联地址、systemd capability、Docker Socket 或宿主机目录 挂载，默认按 L2 以上变更处理。

4. 网络入侵安全基线

4.1 HTTP 与反向代理

  • 公网访问优先经 HTTPS 反向代理；直连端口不得改变 Agent 和宿主机信任边界。
  • k fd 必须支持可信代理传递的动态域名，但只有立即来源位于可信 CIDR 且 X-Forwarded-Proto: https 时才信任该 Host/Origin。
  • 未可信来源的 Forwarded、X-Forwarded-*、Host 和客户端 IP 不得参与授权、安全 Cookie 或审计身份判断。
  • HTTP Server 必须设置 ReadHeaderTimeout、ReadTimeout、WriteTimeout、IdleTimeout、 MaxHeaderBytes 和请求体上限；禁止使用无边界默认值。
  • API 只接受声明的方法和 Content-Type；未知字段、重复冲突参数和超限请求必须明确拒绝。
  • 保留 CSP、HSTS（仅真实 HTTPS/可信 HTTPS 代理）、nosniff、Frame 限制、 Referrer Policy、COOP 和 CORP。
  • 健康检查不得返回版本以外的敏感配置、路径、凭据、错误堆栈或业务数据。

4.2 身份、Session 与抗撞库

  • 密码使用当前项目 Argon2id 强度，不得仅为降低内存而下调算法参数。
  • 昂贵密码哈希必须有小型并发信号量和快速 429；不能让并发登录把容器推到 OOM 边缘。
  • 登录失败按用户与来源进行有界限速；错误信息不得泄露用户名是否存在。
  • Bootstrap Token 一次使用并及时失效；Session ID 登录后重新生成，Cookie 保持 Secure、HttpOnly、严格 SameSite 和限定 Path。
  • 所有改变状态的浏览器请求必须验证 Session 与 CSRF/Origin；反向代理不能绕过该检查。

4.3 输入、命令和 SSRF

  • HTTP 输入先解析为严格结构体，再做长度、范围、枚举和语法验证。

  • SQL、Nginx 模板、Docker URL 和宿主机系统动作不得由 Web 字段拼接；宿主机命令使用固定 可执行文件和独立参数。

  • 命令能力只分为三类，评审不得混写：

    边界允许方式强制限制
    宿主机系统动作Agent 固定动作、结构化参数、固定可执行文件不接受任意命令文本，不进入 sh -c/bash -c
    kejilion.sh 原生交互登记的固定脚本入口与 selector，通过 PTY 保留原生语义固定脚本来源、任务 ID、输入/输出和恢复边界
    目标容器内控制台已认证管理员明确选择真实容器后提交单次容器内命令校验容器 ID/资源版本，限制输入、时间和输出；不得转化为宿主机 Shell

    容器内控制台是 KPanel 的明确管理员能力，不得因使用容器内 /bin/sh 被误判为宿主机命令注入； 反之也不得借“控制台”名义接受宿主机命令、Docker endpoint 或未校验目标。

  • 通用 Panel/Agent 出站 HTTP 只能访问代码或配置登记的可信来源；API 不得提供通用 URL 代理， 也不接受 Socket 地址、Docker endpoint 或代理配置。唯一例外是已认证管理员明确触发的 “文件远程下载”专用动作：仅由无特权 Panel 对公开 http/https 地址执行固定 GET，URL 放在受 CSRF/Origin 保护的 JSON body 中；不得接收自定义方法、请求体、Header、Cookie、 凭据、代理、私网放行或跳过 TLS 选项。该动作必须全量校验 DNS 结果并直拨已验证 IP，逐跳 复核重定向且拒绝 HTTPS 降级，限制 URL/响应头/实际字节/并发/空闲和总时长。通过 Agent 同目录暂存并原子发布；取消或失败时清理尚未提交的暂存文件，若与原子提交窗口重叠则必须按 “结果未知、刷新目录确认”处理，不得声称一定未落盘。审计与错误只记录脱敏来源 origin，不记录 完整 URL 或响应体。若提供跨页面后台下载，完整 URL 仍只能存在于 Panel worker 内存；任务索引必须 有大小、数量、保留期和私有文件权限上限，损坏时 fail-closed。Panel 重启不得自动重放 URL；遗留 active 任务标记 interrupted，要求用户核对真实目录后重新提交。

  • 所有出站请求必须设置超时、禁止意外重定向、限制响应体大小，并验证预期内容结构。

  • 对 Host、路径、查询串、归档名、容器 ID、任务 ID、域名、端口和资源版本分别验证； 不得用一个宽松“通用字符串”校验器覆盖所有场景。

4.4 文件、归档与竞态

  • 文件动作必须限定在明确业务根目录，使用清理后的绝对路径并复核最终目标仍在根内。
  • 不跟随不受信任符号链接；高权限读写在 Lstat 后打开文件，并用打开后的 Stat/inode 或 root-scoped API 复核。
  • 写配置使用同目录临时文件、权限设置、fsync、语法检查和原子替换。
  • 解压前拒绝绝对路径、..、越界链接、硬链接、设备文件、超大单文件、超大总量和条目炸弹。
  • 备份/还原必须校验摘要和结构；还原先进入暂存目录，再原子交换，失败恢复原目录。

4.5 凭据与日志

  • Token、密码、私钥和云平台凭据使用 0600 文件或不回显输入通道，不进入命令行参数。
  • 敏感值不得写入任务 JSON、审计、终端历史、错误详情、URL、镜像标签或 Git。
  • 日志输出采用 allowlist 式字段；转发第三方输出前执行脱敏并限制长度。
  • 测试凭据必须是临时随机值；测试完成后清理，不复用线上 Token 或数据目录。

4.6 Panel、容器和 Agent

  • Panel 最终镜像保持非 root、scratch/最小运行时、只读根文件系统、cap_drop: ALL、 no-new-privileges、受限 PID/CPU/内存和小型 tmpfs。
  • Panel 容器不得挂载 /var/run/docker.sock、宿主机根目录或 Agent 可写状态目录。
  • Agent 权限按实际宿主机动作最小化；新增 capability、可写目录、AddressFamily 或命令 必须给出必要性、攻击影响和撤销方案。
  • Agent 只监听权限受限的 Unix Socket；禁止为方便调试新增 TCP 监听。
  • Docker、containerd、runc 和宿主内核属于运行时攻击面，发布验收必须记录实际版本和已知高危状态。

4.7 供应链

  • GitHub Actions 固定完整提交 SHA；构建镜像、测试工具和远程脚本固定不可变摘要。
  • 生产镜像发布版本标签和 latest 必须指向同一已验证 digest；安装端按 digest 拉取。
  • Go、npm、最终镜像和脚本分别执行漏洞、Secret、配置和完整性扫描。
  • 发布产物保留 SHA-256、SBOM、provenance、源码提交和脚本提交/摘要。
  • 扫描器本身也必须固定安全版本与摘要；不得临时改用未经复核的 latest 扫描器。

4.7.1 依赖清单与稳定候选检测

dependency-policy.json 是依赖检测范围、稳定通道、采用分类、例外字段和 自动化权限的机器真源。至少覆盖 Go/npm 直接与传递依赖、Go/Node 工具链、Docker 基础镜像和 Dockerfile frontend、全部 GitHub Actions、govulncheck/Trivy 以及镜像内受管 kejilion.sh。

  • make dependency-policy-check 在本地和治理门禁中离线检查清单完整性、文件存在性、Trivy 摘要一致性 与自动化权限边界；不得依赖网络结果才能证明规范自身有效。
  • make dependency-report 联网读取各生态正式稳定来源，必须报告每个检测源成功/失败和生成时间。 检测源失败是“未报告”，不能以候选数为零宣称全部最新。
  • GitHub Actions 每周生成版本通道候选，每日对当前 Go/npm 依赖图和 Trivy 源码供应链规则执行安全通告 复核；依赖相关提交仍由主 CI 即时复核。版本候选、漏洞告警和最终采用结论是三个不同状态。
  • npm 检测包含生产/开发、直接/传递依赖，Go 检测包含构建列表全部模块；工具链、基础镜像、Action、 扫描器和脚本不得因不在包管理器中而遗漏。
  • 上游 latest、Release 或分支头只用于候选发现。正式构建继续使用锁文件、完整 Action SHA、不可变 镜像 digest 和脚本提交/摘要；候选检测不得在后台改写这些真源。

4.7.2 稳定版定义与采用决策

“最新稳定版”同时满足：上游正式发布且未撤回，不是 alpha/beta/RC/nightly/canary/preview，仍在安全 维护期，许可证和来源可接受，支持 KPanel 架构与 Linux 环境，并可固定为可复核版本、SHA 或 digest。 Node 使用最新受支持 LTS，而不是数值最大的非 LTS 版本。上游刚发布但存在重大回归或供应链事件时， 应记录为候选被阻断，不伪装成当前版本已经最新。

自动报告只能证明“版本通道稳定”；不能自动证明仍受维护、许可证与来源可信、支持 KPanel 架构和 Linux、行为与资源预算可接受或能够安全回滚。这些条件必须在采用任务中补齐，未补齐前不得把候选写成 “已通过稳定版准入”。

候选类别默认决策启动/决策/完成处置最晚最低验收
已利用、被撤回或可达 High/Critical立即复核，升级、隔离或采用安全旧版缓解1/3/3 天，且第 11 节更严格时限优先L2/L3
当前支持线兼容补丁（包括基座 SemVer Patch）默认跟进；有证据可暂缓7/14/30 天按影响 L1/L2；基座保持 L2/L3 下限
稳定次版本（包括基座 SemVer Minor）批量评估产品/维护收益、契约和资源变化14/30/60 天L2；基座保持 L2/L3 下限
主版本或非 SemVer 的镜像 digest、Action pin、受管脚本 revision 等基座变化独立升级任务，不与无关功能混合30/90/90 天L2/L3
预发布版本默认不采用仅在明确实验窗口内决定，不进入正式发布明确实验分支

期限从一次检测源完整的报告首次确认该行动项时开始计算。完成处置不是强制采用：必须在期限内完成采用、 以可复核证据拒绝，或在 dependency-policy.json 建立有负责人、复核日期、缓解和退出条件的有期限例外。 网络失败或不完整报告不能启动“已全面检测”的计时，也不能重置已经开始的期限；重复发现同一当前/候选版本 沿用最早完整检测时间。兼容评估未通过时应记录精确阻断，不得通过跳过测试、放宽类型检查或改写版本来源 使新版看似可用。

直接依赖与 Go/Node 工具链、基础镜像、构建 frontend、GitHub Actions、扫描器和受管脚本属于行动项。 传递依赖仍保持全量可见，但其跨父依赖范围的 latest 只作为归属信号：通常由拥有它的直接依赖升级、 锁文件兼容刷新或可达漏洞修复带入，不为减少报告数量逐项强升。报告必须分开显示直接/基座行动项和 传递依赖归属信号；安全审计发现可达漏洞时，传递依赖立即提升为安全行动项。

批次边界以兼容与原子回滚为准：Patch 可以在同一生态和同一回滚边界内合批；Minor 只合并同一兼容域且 必须比较契约与资源；Major/工具链/基座一次只处理一个兼容域，必要的适配器可以同行，但不得夹带无关功能。 版本变化幅度决定处理期限，组件位置决定验收下限：例如 Node LTS、Action 或扫描器的 SemVer Patch/Minor 使用 Patch/Minor 时限，但仍作为独立基座任务执行 L2/L3；不得因为验收更完整就把小版本机械拖入 90 天窗口。

SemVer 只是输入，不是结论。采用前还必须比较漏洞可达性、EOL 时间、变更日志、行为和配置变化、 Panel/Agent/kejilion.sh 契约、二进制和前端体积、启动/CPU/内存预算、供应链信任与回滚难度。

4.7.3 例外、自动化与防指标投机

  • 暂缓或拒绝必须记录组件、当前/候选版本、原因、安全与产品影响、临时缓解、负责人、复核日期、 结束条件和回滚点。到期例外和超过季度上限的 EOL 复核必须重新进入报告并使定时任务失败，不能永久 忽略；离线治理校验只检查记录结构，避免到期事项机械阻断无关本地开发。
  • 定时检测只生成报告；候选为零不构成质量目标。“最新率”不得作为绩效指标，也不得为了减少候选而 删除依赖、降低检测范围、改写版本来源或跳过兼容验收。
  • 自动修改只允许在预先明确授权的专用任务分支；main、tag、Release、公共镜像和生产仍须现有明确 授权。依赖机器人或智能体不能自行扩大权限。
  • 采用后按约定观察窗口核对 CI/生产失败、回滚、资源和兼容回退；恶化时优先回退升级或重新评估， 不得通过放宽安全、性能或稳定门禁保留新版。

4.8 持久化与数据库

  • 持久化选型、迁移和回滚必须遵守 storage-strategy.md，不得默认把所有业务数据库化。
  • Docker、Nginx、systemd、系统文件和 kejilion.sh 产物是真实状态；JSON 或数据库只保存 面板自身数据和可丢弃缓存。
  • SQLite 仅用于 Panel 本机数据，使用本地文件系统、最小权限、固定 Schema、参数化 SQL、 版本化迁移和一致性备份；禁止任意 SQL、动态扩展和网络文件系统数据库。
  • 数据库、WAL、SHM、备份、导出和驱动供应链均视为敏感攻击面；Token、Cookie 和密码不得 以明文进入数据库、错误信息或审计。
  • 每种存储都必须有容量、保留期和损坏恢复上限，禁止无界 JSON/JSONL、无界查询和长期双写。

5. 性能预算

预算基于 runtime-performance-baseline.md 和 security-performance-hardening-2026-07-28.md。 同一验收机、相同数据量和相同并发下，以下门槛默认生效：

指标发布预算
Panel 预热后空闲 RSS≤ 32 MiB
Agent 空闲 RSS≤ 32 MiB
256 MiB cgroup 中的登录突发峰值< 192 MiB，且 memory.events.max/oom/oom_kill 不增加
Agent 常规只读采集峰值 RSS< 128 MiB
Panel 冷启动到健康，P95≤ 2 s
/health、Session API，10 并发同机 P95≤ 10 ms，错误率 0
/system/summary 同机 P95≤ 250 ms
主入口 JS gzip≤ 70 KiB
单个懒加载路由 JS gzip≤ 120 KiB
交互终端本机输入到 PTY，P95≤ 250 ms
同场景 P95、CPU 或峰值 RSS 回退不得超过上一个稳定基线 20%

确有业务必要超过预算时，不能静默放宽阈值。变更必须包含：

  1. 数据量和测试环境；
  2. 超预算原因；
  3. 已比较的低成本方案；
  4. 新预算和对低配主机的影响；
  5. 回滚点。

5.1 实现规则

  • 禁止 N+1 Docker inspect、逐项远程请求和无界 fan-out；并发必须有小型固定上限。
  • 相同的并发只读请求可 singleflight 合并，但完成后不保留陈旧状态；写后必须读取真实状态。
  • 缓存必须有容量、TTL、失效和最大对象大小；缓存不得成为第二套业务事实。
  • 大文本静态资源构建期预压缩；指纹资源长期 immutable，index.html 保持 no-cache。
  • 大 JSON 可快速 gzip，但下载、Range、HEAD 和不可压缩内容保持协议正确。
  • 前端按路由和大型终端组件懒加载；不得把完整应用目录重复嵌入多个首屏接口。
  • 采样、排序、摘要和格式化尽量在一次采集内完成；不得为每个并发页面重复读取宿主机。

5.2 存储预算

  • 单个可变 JSON 文件达到 8 MiB、有效记录达到 5,000、整体写入 P95 达到 50 ms， 或持续写入超过每秒 1 次时，必须评审分片、JSONL 或 SQLite，不能直接放宽文件上限。
  • SQLite 方案必须与当前实现比较二进制体积、空闲/峰值 RSS、读写 P95、磁盘放大和恢复时间； 任一指标回退超过 20% 时须说明产品收益和低配主机影响。
  • 数据库连接、事务时长、WAL 大小、分页、查询返回量和历史保留期必须有固定上限。
  • 大日志、终端输出、归档和二进制文件保存在有界文件中，不作为数据库 BLOB 持续增长。

6. 资源占用规范

6.1 默认上限

以下现有边界不得无证据放宽：

资源当前边界
Panel 容器256 MiB、1 CPU、128 PIDs、16 MiB tmpfs
Panel 请求体默认 1 MiB
Agent 请求体64 KiB
Panel 读取 Agent 响应默认 8 MiB
交互终端单次输入/输出块16 KiB / 64 KiB
应用/建站/体检终端日志按任务类型 1–32 MiB 有界
Docker API JSON/日志16 MiB / 1 MiB
Docker 备份还原总量50 GiB，单条目另有限制
Panel Docker 日志10 MiB × 3

新增列表、终端、备份、下载、目录扫描或第三方响应时，必须同时定义：

  • 单对象、单请求、单任务和总量上限；
  • 达到上限时的截断或错误语义；
  • 临时文件权限、清理时机和磁盘不足行为；
  • 并发数、超时、取消和进程回收；
  • 关闭页面、Agent/Panel 重启后的恢复方式。

6.2 生命周期

  • 每个 goroutine、Timer、Ticker、连接、文件、PTY 和子进程必须有明确所有者及退出路径。
  • 请求取消应停止纯读取；已进入安全后台阶段的写任务由独立任务生命周期接管。
  • 连接关闭后 FD、goroutine 和内存必须回落；压测结束 30 秒后不得持续增长。
  • 终端只传输增量块，保留 ANSI；清屏控制序列是输出内容，不能被误判为任务结束。
  • 日志和进度采用追加/有界尾部读取，禁止每次轮询读取整个不断增长的文件。

7. 稳定性规范

7.1 状态与成功判定

  • Docker、系统文件、Nginx、systemd 和 kejilion.sh 产物是真实状态；数据库缓存不是成功依据。
  • 后台任务至少有：排队、运行、等待输入、成功、失败、需要人工处理。
  • systemd 或子进程退出码为 0 只是证据之一；成功必须同时具备完成凭据和产物复核。
  • 页面刷新、弹窗关闭、浏览器退出不终止后台任务；重新进入可恢复进度和终端偏移。
  • Agent 重启后从原子状态文件恢复任务结论；损坏或不完整状态不得被解释为成功。

7.2 写入、重试与回滚

  • 写操作使用 expectedResourceVersion 或等价机制防止旧页面覆盖新状态。
  • 配置变更流程为：读取真实状态 → 备份 → 暂存修改 → 语法/健康检查 → 原子切换 → 复核。
  • 自动重试只用于幂等读取和明确幂等的提交，次数有限并带退避；不得自动重复安装、删除和数据库写入。
  • 错误必须保留真实底层原因并给出已完成步骤；不得返回“完成”掩盖部分失败。
  • 自动回滚只处理可证明安全的步骤；数据库格式升级等不可安全逆转场景标记“需要人工处理”。
  • 停止任务只能在脚本安全阶段执行，不直接强杀正在替换目录、写数据库或更新包管理器的进程。

7.3 兼容稳定性

  • kejilion.sh 与 KPanel 任一端修改后，另一端刷新即可读取真实结果。
  • k fd、IP+端口、IPv4/IPv6、Debian/Ubuntu/Rocky/AlmaLinux、amd64/arm64 按改动范围回归。
  • 新协议必须向后兼容当前稳定 Agent/Panel 的明确版本窗口；不兼容时在安装前失败，不在任务中途失败。
  • 网络断开、Registry 超时、磁盘不足、只读文件系统、端口冲突和第三方脚本退出都必须有确定状态。

7.4 Schema、迁移与恢复

  • Schema 版本单调递增，迁移可重复检测；迁移完成前不得删除旧数据或宣告升级成功。
  • JSON → SQLite 先备份，在单个事务中导入，再核对记录数、关键字段、约束、摘要和 integrity_check，最后原子切换存储标记。
  • 禁止无期限双写。灰度双读只用于短期比对，并必须标注截止版本和删除计划。
  • SQLite 备份使用 Backup API 或 VACUUM INTO 等一致性方式；WAL 模式下禁止只复制主文件。
  • 升级中断、进程重启、磁盘写满、只读文件系统、损坏数据库和回滚到旧版本都必须有测试结论。

8. 用户体验与可访问性

  • 用户体验验收关注“能否完整、可预测地完成运维任务”，不以截图相似或主观好看作为唯一结论。
  • 界面和视觉变更遵守 ui-visual-language.md：有语义文字最小 12px，正文、表单和 操作控件最小 14px，历史低于该基线的样式按受影响功能迁移，不得新增或机械全局替换。
  • 新增或修改的交互至少验证桌面与窄视口、浅色与深色、键盘操作、焦点可见、加载、空状态、失败、 权限/依赖缺失和长文本；终端或固定底栏不得遮挡获得焦点的输入控件。
  • 受影响控件按 WCAG 2.2 AA 目标设计：键盘焦点不能被作者内容完全遮挡；点击目标至少 24 × 24 CSS px，不足时必须有等价控件或足够间距；不依赖颜色单独表达成功、危险或选中状态。
  • 支持浏览器缩放和文本增长；桌面窗口、表格、终端、对话框和移动导航不得产生阻断操作的横向溢出。
  • 动画遵守 reduced-motion；焦点不能触发意外导航、提交或新窗口；关闭弹窗或切换页面不得取消 已进入安全后台阶段的任务。
  • 用户提示必须说明真实底层原因、已完成步骤、资源影响和恢复方式；“失败”“超时”“需要人工处理” 不能统一显示为泛化错误或成功 Toast。
  • 危险操作使用一次普通确认说明影响，不用固定确认词或隐藏按钮；确认后的后端仍执行身份、输入、 资源版本和事务校验。
  • 所有新增文案遵守 internationalization.md；命令、路径、协议和第三方 原始输出保持原文，产品说明和错误恢复提供已发布语言资源。

9. 开发流程

9.1 编码前质量记录

涉及 API、Agent、Docker、系统、脚本、终端或大数据列表的改动，开发前至少回答：

流量路径：
不可信输入：
权限与可写范围：
最坏输入/输出字节数：
最大并发、CPU 和内存：
超时、取消与重试：
真实状态来源与缓存失效：
失败、回滚和重启恢复：
性能预算影响：
网络入侵风险：
受影响业务域与用户旅程：
桌面/移动端、键盘/焦点、多语言和失败反馈：
自动测试、隔离真机、公开产物、生产部署安全核对分别需要什么证据：

没有明确答案时先补设计，不先写实现。

9.2 实现要求

  • 先复用已有类型、限额、任务框架和 kejilion.sh 协议，不平行实现另一套。
  • 新边界先写失败测试：超长、越界、重复、并发、取消、断网和损坏输入，再写成功路径。
  • 性能优化必须保持结果一致，并包含防陈旧缓存、资源上限和并发回归测试。
  • 安全修复必须描述可利用入口、信任边界和复核方式；不得只写“加强校验”。
  • 任何扫描告警忽略都要记录规则、代码位置和不可利用证据，不能只加 suppress 注释。

10. 测试与发布门槛

改动类型必测内容
业务真源/互通脚本或外部产物可发现并管理、KPanel 产物可被脚本继续管理、写后真实状态回读
HTTP/代理Host、Origin、CSRF、Cookie、可信/不可信转发头、方法、Content-Type、超限和慢请求
Agent/系统写入Token、Unix Socket、动作枚举、命令参数、路径/链接、资源版本、回滚和重启恢复
交互终端ANSI/颜色、清屏、连续输入、延迟、断线重连、窗口关闭、日志上限和任务后台继续
Docker/归档受限 Socket、容器并发、路径穿越、链接逃逸、损坏归档、体积炸弹和磁盘不足
前端与 API 性能生产构建、gzip、缓存、路由包大小、同请求合并、无陈旧状态
Store/迁移Schema、事务、并发、限额、敏感字段、损坏输入、备份恢复、迁移中断、回滚和性能基线
依赖/镜像govulncheck、npm audit、Trivy 源码/镜像、Secret、Misconfiguration、SBOM/provenance
界面与用户旅程受影响桌面/窄视口、浅/深色、键盘与焦点、缩放、多语言、加载/空/失败态和控制台错误

发布前至少执行：

go test ./...
go test -race ./internal/panel ./internal/auth ./internal/dockerx
npm --prefix web test
npm --prefix web run build
make security-audit
make verify-release

另外必须：

  1. 用固定摘要的扫描器扫描源码和最终 scratch 镜像；
  2. 在生产同限制下启动镜像并验证非 root、只读根、capability、PID/CPU/内存；
  3. 复跑受影响性能基准并与最近稳定报告比较；
  4. 实测 k fd 可信 HTTPS 反代和伪造代理头拒绝；
  5. 对 L2/L3 系统动作执行失败注入和回滚验证；
  6. 记录实际 Docker、containerd、runc、内核及 Agent/Panel 协议版本；
  7. 涉及 systemd capability、沙箱或进程可见性时，L2 必须通过候选中完整、未放宽的正式 unit 启动 Agent，并复核真实业务输出；脱离 unit 直接以 root 运行只能用于定位，不能作为上线证据。

自动门禁对应关系：

  • CI 固定执行核心特权包 -race、govulncheck、npm audit 和源码 Trivy 扫描；
  • Release 在 CI 基础上扫描最终镜像，并在 256 MiB、1 CPU、128 PID、非 root、只读根和 cap-drop ALL 条件下启动验证；
  • make verify-release 统一执行 govulncheck、npm audit 并复用 scripts/security-scan.sh， 不得另建参数不同的本地扫描路径；
  • Trivy 使用固定镜像摘要。项目为 Go 1.17+ 模块，源码扫描跳过仅保存历史校验和的 go.sum， 仍扫描 go.mod，并以 govulncheck 和最终 Go 二进制扫描校验实际依赖与调用可达性；这不是 漏洞 ID suppress，若 Go 模块版本或扫描器行为变化必须重新复核。

10.1 发布画像、节奏与验收记录

候选冻结前填写发布画像：业务域、变更面（展示、只读、宿主机写入、协议/数据、部署）、受影响 用户旅程、风险等级、迁移、性能、安全、稳定和体验证据。发布后按 release-acceptance-template.md 记录候选、主线、Release、公开产物、 隔离真机、生产部署安全核对和回滚，缺少的层级必须标记未验证。

KPanel 允许高频小步发布，但版本必须是可解释的用户价值或紧急修复单元：

  • 同一页面、同一交互问题在候选冻结前出现的连续微调应聚合，减少无业务收益的生产部署和备份；
  • 候选冻结后的安全修复、回滚修复或独立缺陷进入新 patch 版本，不移动旧 tag 或覆盖已发布镜像；
  • 不设置主观的最短发布间隔。至少按滚动 14 天和最近 20 个版本分别统计稳定标签形成的正式发布频率、 有生产完成证据的部署频率及数据覆盖率，并统计提交到生产用时、变更失败/回滚/紧急热修复、恢复时间 和重复发布原因，结合吞吐与稳定性判断节奏；
  • 发布基础设施、执行器、验证通道或证据无效导致必需步骤失败/重试时另计流程异常：首次生产写操作前 被拦截时不计变更失败；生产写操作后若造成服务退化、回滚、紧急热修复或重复发布，则两类同时计入； 产品载荷单独失败只计变更失败；
  • 流程异常计数大于零时，使用“阶段/权威入口/根因类别”稳定指纹记录生产写前后位置、影响、恢复和 永久处置。同一指纹在滚动 5 个正式版本内出现 2 次，必须在下一次 L3 生产写前修复唯一脚本、Runner、 夹具或预检并补回归；不可控上游瞬时故障可以建立有期限例外，但不删除证据或降低 fail-closed；
  • 候选冻结时同时冻结执行方案；SSH 身份、运行时、固定脚本、跨 Shell 参数和证据解析在生产写前于 非生产环境预检。生产写后不临时拼接新的多层命令，入口失效时先保持/恢复健康，再修复唯一入口并重验；
  • 数据不足时先建立基线；出现安全事件、数据损坏、回滚或生产故障时立即复盘根因和逃逸门禁， 不能只通过放慢发布掩盖流程缺陷，也不能以高频为由省略证据。

11. 漏洞响应

漏洞优先级由“是否可从网络到达、是否已被利用、权限影响和运行位置”共同决定，不能只看 CVSS：

级别条件要求
紧急CISA KEV；或无需登录的 RCE、鉴权绕过、容器逃逸、宿主机/凭据读取阻止发布；确认影响后 24 小时内修复或隔离
高网络可达的 High/Critical；登录后可到达 Agent/宿主机的提权链阻止发布；确认影响后 72 小时内修复或有效缓解
中依赖存在但调用路径不可达、仅构建期存在、需要本机先决条件记录调用证据和暴露窗口，14 天内升级或重新评估
低不可达且影响低，无公开利用纳入常规依赖升级，不得永久忽略

当上游尚无修复版本时，优先移除暴露入口、禁用受影响协议、固定安全旧版或隔离组件；这类临时缓解 只能限制攻击面，不能借机限制合法管理员业务动作。

持续关注来源：

  • CISA Known Exploited Vulnerabilities；
  • Go Vulnerability Database 与 govulncheck；
  • npm advisory、Node.js security releases；
  • Docker、containerd、runc、Linux 发行版安全公告；
  • GitHub Actions、构建镜像和扫描工具自身供应链公告。

12. 代码评审核对

  • 未把合法管理员能力削减包装成安全改进。
  • 新网络入口、代理头、外联地址和权限变化已明确。
  • 所有输入、响应、并发、缓存、日志和临时文件都有上限。
  • 没有宿主机任意 Shell、任意 URL、任意 Docker endpoint 或任意文件路径；脚本 PTY 与容器内 控制台符合第 4.3 节各自边界。
  • 页面关闭、超时、断网、重启和部分失败后状态可恢复。
  • 性能预算通过，或已记录超预算证据和新预算。
  • 安全扫描结果按可达性人工复核，没有无证据 suppress。
  • k fd、kejilion.sh、Agent/Panel 和真实状态读取兼容性未退化。
  • 受影响用户旅程在声明的视口、键盘/焦点、语言和失败状态下可完成。
  • 自动测试、隔离真机、公开产物和生产部署安全核对的证据层级没有混写，未验证项已列出。
  • 浏览器长测使用登记的非 108 环境和后台终态；时长/循环数与风险对应，未机械套固定 soak。
  • 存储选型符合产品查询与增长需求，权威来源、限额、迁移、备份和回滚均已明确。
  • 发布产物有 commit、digest、SHA-256、SBOM、provenance 和回滚点。

13. 规范依据与维护

本规范参考：

出现重大安全事件、架构边界改变、资源限制调整或稳定基线更新时立即复核本规范；无事件时至少每年 复核一次。预算更新必须同时更新基线报告和验收证据，不能只改本文数字。