1. 项目概览

**StackPier 已经形成“登记服务器 → 准备配置和程序 → 创建项目 → 部署 → 更新与启停 → 安全卸载”的正式代码闭环。当前最重要的状态是：第 1–3 阶段已有验收记录，第 4 阶段的 4.1–4.6 已进入本地主线，但仍待统一用户验收，真实 Docker/systemd 项目部署尚未验证；第 5–7 阶段没有启动。**这与“整个原型已经可用”或“当前版本已经部署到真实环境”是不同的结论。当前状态 (line 9)

本报告以 2026-10-02 的当前本地工作区为调查对象，交叉阅读了有效需求、设计、交付与验收记录、正式前后端源码和相关测试。本次没有运行测试或构建，没有启动实例、连接服务器、读取运行数据库或凭据，也没有修改任何文件。

它解决什么问题

StackPier 面向个人维护约 4–6 台服务器、十几个项目的场景：把分散在服务器上的应用、部署文件、程序版本和操作结果放进一个管理界面，同时保留每次操作的依据和结果。

它主要管理两种运行方式：

• Docker Compose：用一份配置描述一组容器、镜像、端口、文件和数据卷。
• systemd：使用 Linux 的服务管理器运行用户提供的现成程序及其配置文件。

同一个应用部署到两台服务器上，是两个独立项目；MySQL、Redis 也作为独立项目管理，不默认附带在每个应用中。管理对象与规模 (line 5)

可以把它管理的核心对象理解为：

各部分怎样协作

浏览器是操作界面，Go 控制器负责作出业务判断并执行，SQLite 和控制器文件保存管理资料，SSH 负责访问被管理服务器。

具体分工如下：

1. 浏览器界面展示资料、收集输入、显示预览和结果，通过 HTTP 接口访问控制器。浏览器不直接连接 SSH。
2. Go 控制器是一个服务进程，内嵌已经构建好的网页，处理登录、资料维护、操作受理、后台执行和结果核对。运行正式程序时不需要 Node.js。
3. SQLite是控制器本地的文件数据库，保存服务器、配置、项目、操作记录、资源保护及观测结果。
4. 控制器文件保存实际程序字节、集中配套文件、上传暂存和执行使用的程序副本；数据库主要保存这些文件的身份、摘要和引用。
5. SSH是控制器访问目标机器的加密通道。所有受管系统命令都经过公共 Go SSH 实现；即使管理控制器所在机器，也不使用本地命令回退。
6. 被管理服务器真正运行容器或 systemd 服务，保存交付文件、业务数据以及证明操作是否结束的记录。

正式程序确实组装了服务器、程序、配置、项目、环境准备，以及 Compose/systemd 执行适配器，并非只有界面入口。程序组装 (line 118)

明确不做、暂缓及尚未实现的范围

• 明确不做：网页交互式 SSH 终端、任意远程文件浏览器；不接管任意外部已有部署，不负责拉源码、编译应用，不自动修复或自动切主。人工操作界面边界 (line 5)
• 暂缓：业务备份、恢复，以及专属计划、保留策略和清理能力。卸载保留数据、原位复用及本地文件发布中断处理，不等于恢复了这组功能。备份与恢复暂缓决定 (line 3)
• 尚未实现：巡检与通知、提示性项目依赖、防火墙、Cloudflare DNS、FRP 专用角色流程、MySQL 从库初始化等，分别属于第 5–7 阶段。
• 应用本身的边界：个人实例、单一实例访问密码、仅提供 HTTP；没有多用户权限体系、内置 HTTPS 或通用工作流编排。

2. 当前开发状态

本次调查的版本

以上来自本次本地 Git 读取。**没有联网刷新远端记录，因此“当前远端究竟是什么版本”未作独立确认。**文档也明确记录当前原型版本尚未推送、发布；其中所称在线 Pages 仍为 10fef07，本次没有访问网站验证。原型版本与发布记录 (line 10)

实现、工程验证与用户验收

下面的“历史验证”是仓库交付记录和提交说明所记载的事实，不表示测试本次重新通过。

阶段证据集中在交付记录 (line 15)、第 3 阶段验收结论 (line 7)和第 4 阶段交付记录 (line 5)。

第 4 阶段“全部子阶段完成后统一验收”是已有明确安排，不是本次调查推导的新规则。统一验收安排 (line 50)

合并、推送、部署要分开看

最新状态与上述区分一致。最新两轮交付状态 (line 5)

3. 模块划分与关系

从使用者看

当前开放的工作区主要是五个业务页面：服务器、部署配置、程序文件、项目、操作记录。初始化和登录位于工作区之外。

• 服务器回答“管理哪台机器、如何确认它、当前基础环境怎样”。
• 部署配置回答“准备把什么配置用于部署，哪些文件随之交付”。
• 程序文件回答“有哪些可用程序与配套文件，当前实际字节是什么”。
• 项目回答“哪份配置在某台机器上形成了什么部署，草稿和运行版本有什么区别”。
• 操作记录回答“刚才究竟做了什么、哪些已证实、哪些仍不确定”。

总览、FRP、巡检与通知、防火墙、DNS、设置虽然出现在导航里，但正式界面明确禁用为“尚未开放”，没有把模拟页当作正式功能。正式导航与页面装配 (line 18)

从代码看

“适配器”在这里指：把业务动作转换为某种目标环境下的固定检查、命令和结果解释的实现。

模块关系图

实线表示当前正式代码中的连接；虚线表示尚未实现的设计方向。

flowchart TB
    UI["浏览器：服务器、配置、程序、项目、操作记录"]
    API["实例访问与 HTTP 接口"]
    S["服务器与环境"]
    C["共享配置"]
    F["程序与集中配套文件"]
    P["项目草稿、部署参照与状态"]
    O["公共操作链：预览、冻结、保护、记录、核对"]
    E["环境安装 / Compose / systemd<br/>更新、启停、卸载适配器"]
    X["公共 Go SSH"]
    T["被管理服务器：服务、文件、业务数据"]
    DB[("SQLite 与加密正文")]
    DISK["控制器文件目录"]

    UI --> API
    API --> S
    API --> C
    API --> F
    API --> P
    API --> O
    C --> P
    F --> P
    S --> O
    P --> O
    O --> E
    E --> X
    S --> X
    X --> T
    C --> DB
    P --> DB
    S --> DB
    O --> DB
    F --> DB
    F --> DISK

    subgraph FUTURE["尚未实现"]
        M["第 5 阶段：巡检、通知、依赖"]
        N["第 6 阶段：防火墙、DNS"]
        R["第 7 阶段：FRP、MySQL 复制"]
    end
    M -.-> P
    M -.-> O
    N -.-> O
    R -.-> P
    R -.-> O

    classDef planned fill:#f6f6f6,stroke:#999,stroke-dasharray:5 5;
    class M,N,R planned;

这些公共能力的复用意义是：

• 实例访问统一保护业务入口。
• SSH统一主机密钥校验、认证、超时、参数和输出边界。
• 操作记录把环境安装、Compose 和 systemd 的结果用同一种方式呈现。
• 资源保护防止两个操作同时改同一个项目、目录、端口或卷。
• 状态核对要求各适配器提供实际证据，公共链据此判断结果。

它共享的是这些规则，不是允许用户编写任意流程的通用执行引擎。

4. 已有功能清单

以下能力已核对到正式页面、后端入口及相应业务实现；远端执行能力仍受后文的平台、输入和验收边界限制。后端的实际开放范围有统一登记，包含配置、程序、项目、服务器、预览和操作等入口，没有未来巡检、网络或 FRP 的正式路由。已实现接口登记 (line 31)

实例、服务器与环境

使用边界及历史观测处理见运行说明：实例与服务器 (line 46)、环境检查与准备 (line 76)。

共享配置、程序与文件

程序单文件上限为 128 MiB，当前目录限额为 128 个程序、512 MiB；扫描候选有效期为 10 分钟。这些是防止无限扫描和上传的工程边界，不是运行兼容性保证。程序使用说明 (line 5)、源码限额 (line 6)

项目草稿与共享更新

新入口已取代旧的三步创建界面。内部仍保留普通应用/MySQL/Redis 相关规则，当前普通入口根据明确的常见数据库镜像辅助判断，不再要求用户填写类别；FRP 专用流程未开放时不能通过普通部署替代。最新入口需求 (line 28)、内部类别判断 (line 10)

部署、运行与结果

对应使用入口见项目部署与启停 (line 3)；日志确实经现有部署参照和公共执行容量读取，未做成任意远端日志浏览器。日志实现 (line 21)

5. 执行逻辑与完整流程

5.1 先区分本地保存与远端操作

不是所有“保存”都会走部署协议：

• 本地资料修改主要是数据库事务和修订检查，例如修改配置、编辑项目、改名。
• 本地文件发布另外有文件处理记账，协调磁盘文件与数据库登记。
• 远端写操作采用“预览 → 明确确认 → 冻结与保护 → 分步执行 → 实际核对”。
• 服务器、环境只读检查界面点击即执行，前端在内部完成公共预览和受理，不额外弹确认框。

四个机制解决什么问题

这里的幂等保证的是控制器识别同一次请求，不能据此声称远端命令可以随意重复执行。事务表示本地一组数据库修改一起提交或回滚，也不表示远端服务、文件和 SQLite 构成一个大事务。

资源保护按实际机器身份分组，路径会检查父子交集，端口会考虑协议、地址和通配监听；兼容的只读保护可以共存。资源交集实现 (line 40)

一次远端写操作的共同过程

1. 前端读取最新已保存资料，收集目标状态和选择，申请预览。
2. 后端检查本地关系并只读检查目标，列出交付文件、程序或镜像身份、资源、停服和阻断项。预览会保存本地记录，但不先部署。
3. 确认时重新核对。草稿、程序、连接、目标资源等相关条件改变，旧预览会被拒绝。
4. 受理时冻结资料并登记保护。操作、步骤、重复请求绑定、凭据引用及资源保护在短事务中保存；程序需要时建立独立执行副本。
5. 后台逐步执行。每步先核对前提、持久化“准备派发”的意图，再发命令。
6. 无论命令成功还是报错，都读取实际效果；结果不足以证明安全时停止后续写步骤。
7. 保存结论并反馈界面。全部完成才更新完整部署参照；部分完成和未知保留各自事实，未知不解除相关保护。

受理中的重新规划、冻结和短事务在项目受理实现 (line 110)，执行后的无条件读回在执行实现 (line 278)。

sequenceDiagram
    actor U as 用户
    participant B as 浏览器
    participant C as Go 业务与操作链
    participant D as SQLite/控制器文件
    participant S as SSH/目标服务器

    U->>B: 选择操作并生成预览
    B->>C: 最新修订、输入和目标状态
    C->>D: 读取草稿及引用
    C->>S: 只读检查身份、能力和资源
    C-->>B: 清单、影响、阻断项

    U->>B: 明确确认
    B->>C: 预览标识 + 本次请求标识
    C->>S: 再次只读核对
    C->>D: 冻结输入、登记操作和资源保护
    C-->>B: 返回操作编号

    loop 每个受支持步骤
        C->>D: 保存派发意图
        C->>S: 执行固定动作
        S-->>C: 命令返回或连接异常
        C->>S: 读取结束证明和实际效果
        C->>D: 保存命令事实及核对结论
    end

    B->>C: 查询原操作
    C-->>B: 成功/失败/部分完成/未知
    Note over C,D: 未知保留保护；再次核对不重发写命令

公共操作链有四个执行槽，容量不足直接拒绝，不排队。关闭浏览器或弹窗不取消已经受理的后台操作。

5.2 服务器登记、主机信任、检查与连接维护

登记与信任

前提是目标已有 SSH 服务及用户准备好的认证、管理权限。

流程为：

填写连接 → 只探测主机公钥 → 用户从可信来源核对指纹 → 固定完整公钥 → 认证 → 读取机器身份 → 保存连接、身份和加密凭据。

首次候选探测在主机公钥阶段停止，不先尝试发送用户凭据。确认后不仅检查地址，还结合主机公钥、机器身份和管理用户身份识别同机重复登记、身份冲突。SSH 探测与固定校验 (line 67)、登记业务 (line 178)

成功判定是身份与输入一致且保存完成，不是“端口能连上”。身份读取失败、主机公钥变化、同机歧义等都会拒绝登记。下一步可以发起服务器或环境检查；登记本身不证明环境已经具备部署能力。

服务器检查

点击检查后，后端先保存操作，再通过固定 SSH 读取命令采集基本资料，保存本次结果和时间。字段无法可靠取得时显示未知，不能拿旧值冒充本次结果。

失败后仍能在操作记录看到尝试；服务器详情保留历史完整观测及其时间，用户可修正连接或权限后再次检查。服务器检查流程 (line 107)

修改连接与删除

改名称、分组仅改本地资料。改地址、端口、用户或凭据时，先检查新连接仍符合原公钥和机器身份，确认后保存时再查一次；修订冲突、身份改变或资源保护都会阻断，旧连接不被覆盖。

当前这里核实的是机器身份，没有在保存连接时遍历核对原有项目；这是与需求表述之间需单列澄清的落点，见第 7 节。连接身份核对 (line 127)

删除连接只处理本地记录和当前凭据，不执行远端卸载。重新登记同一身份可以恢复原 ID；重装或换主机公钥后的重新认领尚未开放。

5.3 环境检查、准备预览与安装

环境检查解决“目标是否具备运行方式的基础条件”，部署预览解决“这个具体项目能否在此执行”，两者不能互相替代。

1. 用户选择 Compose 或 systemd，点击只读检查。
2. 后端按已有 root/非交互 sudo 管理方式读取工具、服务和权限。
3. 结果逐项区分：已兼容、明确缺失、已有但不兼容、无法判断。
4. 只有已证实缺失且有安装适配能力的项目可进入准备预览。
5. 预览明确包、版本、来源、新增依赖、空间和可能启动的服务。
6. 确认时再次核对，取得整机环境写保护后执行安装。
7. 命令结束或报错后，重新检查所选组件的实际结果。

当前固定安装范围是：

• Debian 13 / amd64 / APT 3.0.3；Engine 安装还有现有 systemd 条件。
• Ubuntu 24.04 / amd64 / APT 2.8.3：只补装已有 Docker 缺少的官方 Compose 插件。

不会改软件源、刷新索引、升级已有包或给用户新增 sudo 授权；版本或来源等条件不符时保持阻断。当前安装支持边界 (line 84)

安装结果未知时，保留环境保护和凭据引用。下一步是“再次只读核对”，不能直接重新安装或强行清锁。已有历史实测仅证明特定 Ubuntu 正常流程，不覆盖所有真实故障和平台。

5.4 配置创建修改、程序扫描上传与发布

共享配置保存

前端提交名称、运行方式、原文和映射；后端校验基本格式、大小、名称及引用约束，在事务中写入新的加密正文、更新修订和映射。

保存阶段不要求完整部署语义已经正确，因此语法尚有问题的正文可保存；部署预览才完整解析和阻断。

如果其他页面先改了配置，旧修订保存失败，界面保留输入供对照。被项目引用时，删除和更改运行方式受阻。配置保存事务 (line 82)

程序扫描与确认登记

ELF是 Linux 常见的可执行文件格式。扫描只读取它的结构和架构信息，不执行程序。

流程是：

扫描顶层普通文件 → 产生带摘要和期限的候选 → 用户确认名称/架构槽及是否替换 → 再次检查源文件没变 → 暂存、同步、发布文件 → 数据库切换当前登记 → 清理可清理的旧文件。

“架构槽”指同一程序名称下某种操作系统、架构和变体的当前文件位置。它不是历史版本库。

扫描后文件变化需重扫；替换时当前修订或文件状态变化也会拒绝。磁盘发布与数据库提交不能形成一个事务，因此用文件处理记账记录已经走到哪一步。登记实现 (line 25)、文件发布与恢复 (line 109)

网页上传

前端选择文件并提交上传信息，后端接收后检查大小、摘要和 ELF。浏览器进度到 100% 仅说明发送完成，仍要等待服务端校验并明确确认登记。

响应丢失时按原上传标识查询；已经受理发布则查询或核对文件处理记录。取消只清理本次未发布暂存，不能撤销已发布程序。

这里的“核对与恢复”可以继续完成本地已受理的文件发布；它与远端操作“只读核对、绝不重放命令”的规则不同。

配置映射上传

映射文件走另一条发布规则：先接收到暂存，保存配置时，在同一数据库事务中把文件标为已发布并建立映射；取消只处理未发布内容。映射发布事务 (line 52)

以后替换程序页中的 ELF 当前文件，不会改变已经固定为映射文件的字节。

5.5 项目创建、编辑、引用与显式采用共享更新

创建与编辑

项目页现在只选配置和服务器，确认后：

1. 前端先读取配置当前修订。
2. 后端在事务中检查服务器、配置、同机名称以及适用的 MySQL 唯一占用。
3. 复制原文和映射，建立独立项目 ID、草稿修订和来源关系。
4. 前端进入正式部署预览，初始目标为运行。
5. 缺程序、运行身份、文件或目标能力时阻断部署，但保留项目供补充。

创建与远端操作各自有请求去重。因此创建响应不明时可“核对创建结果”，不需要猜测并重新创建。创建实现 (line 94)、前端创建衔接 (line 7)

项目编辑可以维护：

• 完整正文；
• 程序名称、变体；
• systemd 的运行用户和组；
• 项目内配套文本和环境文件；
• 集中文件到目标绝对路径的映射。

这些修改统一受项目修订保护。保存只形成下一次可应用的草稿，不修改远端服务。

采用共享更新

共享配置更新后，项目显示“共享当前修订”和“已采用修订”的差别，独立正文和映射仍保持原值。

采用过程是：

选择同运行方式来源 → 比较当前项目与共享原文、映射 → 明确确认覆盖 → 校验双方仍是所见修订 → 复制为新项目草稿并保存采用结果。

有本地正文覆盖或映射变化时要求明确确认。程序关联、运行身份等其他项目资料保留；不会自动文本合并，也不自动执行配置应用。

响应丢失后查询原采用结果。已经成功的采用不会因为后来项目又编辑了就被当成新请求重复执行。采用实现 (line 121)

5.6 Compose 首次部署

前提是项目输入完整、目标满足当前支持门槛，而且待创建的载体和资源没有冲突。

预览阶段会解析完整 Compose 模型，包括变量来源、环境文件、配置文件、镜像、端口、网络、卷、挂载和运行身份。没有登记的文件或环境来源不能隐式从控制器目录或登录环境中补上。

镜像会固定到 digest，即对应具体镜像内容的身份摘要。受理后不会因为同一个 tag 又发布了新镜像，就悄悄换成新内容。

正式顺序为：

1. 交付冻结文件，保留用户原文，并核对目标原生 Compose 解析结果。
2. 拉取固定平台、固定 digest 的镜像并核对。
3. 创建明确归属本项目的容器等载体。
4. 根据请求启动，或保持停止。
5. 读取实际镜像、挂载、端口、网络、运行及健康状态。
6. 全部必需效果证实后，保存完整部署参照。

这个顺序存在于正式适配器中，而非仅在文档描述。Compose 步骤生成 (line 79)

成功不只看“容器存在”：

• 普通应用没有业务探测时，可以部署及运行核实成功，同时健康仍为未知。
• MySQL/Redis 请求运行时必须具有当前支持且可核验的就绪检查。
• 请求停止时，必须实际停止，健康为不适用。
• 端口映射存在不代表外网可达；不会自动改防火墙或 DNS。

文件漂移、镜像身份无法确定、端口占用、外来资源等会阻断。执行中发生部分交付时保留分项事实，不自动回滚或换回旧镜像。Compose 执行与成功边界 (line 30)

5.7 systemd 首次部署

前提除了服务器能力，还包括：

• 已准备匹配目标架构的程序；
• 已存在且明确选择的运行用户、组；
• unit，也就是 systemd 服务配置文件，与这些身份和路径一致；
• 引用文件、依赖服务及权限可核验。

流程为：

1. 解析受支持的单个服务配置，核对目标、用户、组、依赖和空闲路径。
2. 按目标架构选择当前程序，受理时建立固定字节的独立副本。
3. 交付程序、正文和配套文件，核对内容、归属与权限。
4. 安装 unit，运行原生配置验证并重新加载服务定义。
5. 如请求运行，检查运行身份确实能读、执行程序及使用数据目录，然后启动。
6. 核对服务状态、进程身份、实际执行文件摘要及进程组，形成结果。

正式适配器确实建立了交付、安装和可选启动步骤。systemd 执行步骤 (line 232)

这里有两个容易误解的边界：

• 上传校验通过不等于可部署。当前动态链接 ELF 会被阻断；缺架构、依赖或权限证据同样不能执行。
• 本次启动不等于开机启动。代码不执行 enable/disable/preset，不替用户改变开机启用策略。

文件交付、unit 安装和启动之间不是一个跨目录事务。失败后不会启动混合版本现场，也不自动回滚。systemd 核对与启用边界 (line 24)

5.8 配置应用、程序或镜像更新

这三件事通过不同输入选择明确区分：

如果新配置增加服务或改变镜像引用，不能继续假装完全保留旧镜像；需要把相应镜像变化纳入选择。

预览比较完整内容，列出停服范围。内容没有实际变化时，不执行写入、不重启、不伪造新的应用代次。应用代次是完整应用内容变化的版本序号，和操作次数不同。

• Compose：先准备新文件和镜像，再停止项目服务，替换已核验文件、重建受影响载体，最后按目标状态启动。
• systemd：先准备新文件及程序，证明停止后替换，再验证和重新加载 unit，最后按目标状态启动。
• 保留旧 systemd 程序时，读取并核验远端已部署字节，不偷偷改用控制器里刚上传的新版。

业务数据位置变更不会被当作迁移执行；数据库镜像升级没有已验证兼容路径时阻断。部分失败保留旧完整参照和新的现场事实，不继续启动混合版本。变更流程 (line 7)

5.9 启动、停止和重启

这些动作只操作已经应用的载体和内容。项目有未应用草稿或控制器有新程序，并不会被一起带入。

启动、停止都要预览并核对当前载体身份。重启还要求完整证据链：

重启前实例 → 已全部停止且无残留 → 启动后实例 → 能证明是本次重新启动。

所以，“现在看起来运行着”不足以证明重启成功。Compose 会结合容器与启动时间等证据；systemd 会结合本次运行标识、时间和进程证据，不能只靠 PID 是否变化。

停止无法证实时不继续启动；重启证据不足保持未知。单纯启停不增加应用代次。只有明确停止意图和实际停止都成立，才记为用户主动停止；这份基础记录已经有，但未来的告警抑制尚未实现。启停执行设计 (line 17)、运行基线保存 (line 81)

5.10 卸载、保留数据与原位复用

卸载预览把资源分开列出：

• 服务载体，如容器或 systemd unit；
• 本项目交付的配置、程序及映射文件；
• 专属业务数据；
• 外部或共享资源。

**数据默认保留。**显式删除仅限能证明属于本项目、没有其他使用者的专属数据项；外部资源和网络不会被顺带删除。

执行先证明服务停止，再移除明确身份的载体、受管文件，最后按选择处理数据。不会用宽泛的全局清理命令代替逐项判断。卸载计划与数据选择 (line 82)

需要特别区分：

载体已移除、数据删除失败时，项目可以是“已卸载”，而本次操作仍是“部分完成”。

源码测试明确覆盖了这种组合，因此不能只看项目生命周期判断整次操作成功。卸载分项结果测试 (line 94)

原位复用要求原项目有完整成功且已解除保护的卸载记录。用户明确选择原保留数据后，再核对来源、路径、身份、权限、占用和兼容性；不按目录名相同自动接管，不改变保留数据的原位置。复用核验 (line 12)

5.11 操作结果、失败与中断后的核对

必须分清三层：

反过来，命令返回零，但服务没达到目标，操作仍会失败、部分完成或未知。

这不是仅停留在设计的原则：测试明确包含“命令报错但实际成功”“零退出码但实际失败”“读回失败”“尚不能证明结束”等情形，且要求不改写原退出码。本次只阅读了这些测试，没有执行它们。结果判定测试 (line 271)

发生断连、控制器中断等情况时：

• 能证明尚未派发的部分按未执行处理。
• 可能已派发而效果不明的部分保留未知与保护。
• 控制器重启会处理持久记录，不自动重放项目写命令。
• 用户“再次只读核对”只检查已派发步骤，追加新证据，再计算结论；不会续跑未完成步骤。
• 读回仍失败，当前仍未知；历史有效观测保留原时间，不能顶替当前证据。
• 只有结果及资源安全已得到足够证据，才释放相应保护。

核对入口和实际循环中只有观察调用，没有重新执行调用。只读核对实现 (line 109)、启动时处理中断操作 (line 247)

已知失败或部分完成且保护释放后，能做什么取决于当前生命周期及对应入口；不存在通用的“一键继续剩余步骤”。

5.12 两个虚构例子串起全过程

以下只是说明流程，不是可直接部署的配置，也没有实际执行。

例一：Compose 项目“商品目录”

假设目标服务器是文档示例地址 203.0.113.10，已经具备兼容 Docker/Compose。

1. 登记服务器，核对公钥，运行服务器和环境检查。
2. 建立“商品目录”共享配置，描述应用镜像、端口和专属数据；配置文件通过配套文本或文件映射提供。
3. 从“部署项目”选择配置和服务器，生成独立草稿；缺少的引用在详情补齐。
4. 预览确认镜像具体身份、端口无冲突、数据归属和目标运行状态，再部署。
5. 日后修改共享配置，原项目仍运行旧内容；先在项目中比较并采用，再“应用配置”，默认保留旧镜像。
6. 要升级应用镜像时，单独选择该服务的新镜像并预览更新。上传文件或修改共享配置本身都不会触发它。
7. 停止、启动或重启只作用于已经应用的内容。
8. 卸载默认保留数据；以后在同一项目中选择原保留数据并核验，才原位部署。

若第 4 步创建了容器却无法读取最终状态，结果保留未知；应查询原操作并只读核对，不能重新点一次部署来猜测。

例二：systemd 项目“报表服务”

假设目标为 203.0.113.20，已有运行用户 demoapp，程序是适配该机器的静态 Linux ELF。

1. 登记并检查服务器，确认 systemd、运行用户和工具条件。
2. 上传“报表服务”程序，等待校验后明确确认登记。
3. 从共享 service 配置创建项目；在详情按项目显示的实际路径补齐程序引用、ExecStart、运行身份及环境文件。
4. 预览确认后，控制器冻结程序副本，交付文件、安装和验证 unit，再启动；开机启用状态不自动改变。
5. 上传新版程序后，旧服务仍继续使用已部署字节；选择“更新程序”才会形成新操作。
6. 只改参数时使用“应用配置”，默认保留远端已经部署的程序。
7. 重启要证明旧运行已停止并出现本次新运行；单看 active 不够。
8. 卸载保留数据和项目历史；完整成功后可以明确复用原数据重新部署。

这也说明：两字段“部署项目”是简化创建入口，不代表任意共享模板都已经具备一次完成部署的全部资料。

6. 数据、状态与文件

核心对象之间的关系

最关键的是四份内容不能混为一谈：

共享配置当前版 → 项目独立草稿 → 某次操作冻结输入 → 最后完整应用的内容。

此外还有远端实际观测，它可能与最后完整应用记录不一致。例如外部有人改了文件，或一次更新只完成了一部分。

项目完整参照只有成功时推进；部分结果及未知另存，历史有效运行观测也有独立查询。部署事实保存 (line 89)

什么存在哪里

以下是源码规定的运行时位置，不是本次读取了这些运行目录。

本地项目链接只是集中内容的引用，不是把控制器目录原样传过去。远端传输的是经过核对的文件字节。链接同步异常会给出本地缺项，不能因此覆盖外来文件；数据库保存和目录链接同步也不是一个跨系统事务。映射目录规则 (line 5)、链接异常反馈 (line 27)

项目改名不会改变这些以稳定 ID 形成的目录。

文件映射与项目内配套文件的区别

• 项目内配套文本有项目归属、受控相对路径和权限，正文加密存储，部署时形成文件。
• 集中映射文件按文件身份引用，用户指定远端绝对目标路径。
• systemd 主程序关联另外决定可执行程序、架构和执行权限。把程序选进普通文件映射，不会自动把它变成 systemd 主程序。

目录外映射首次只允许创建不存在的目标；以后只允许更新本项目交付且未被外部修改的内容。普通映射权限为 0644，目录外文件由 root 持有，因此不能把它当成任意秘密文件或可执行文件的权限管理入口。映射交付与权限 (line 11)

用户看到的状态是什么意思

列表的“运行／停止／异常”是压缩摘要：

• 草稿、已卸载且没有运行观测时归到“停止”，并不是已经通过 SSH 证明服务停止。
• 部分完成、当前未知、没有有效观测或健康异常等会归到“异常”。
• 详情仍展示原始生命周期、当前和历史观测。

这套规则在列表状态实现 (line 3)中明确存在。

**刷新项目页面不会自动检查远端状态。**目前没有周期巡检，不会因为时间过去就持续发现服务故障；应看观测时间，不能把显示“运行”理解成实时保证。

引用保护、事务和加密

• SQLite 不使用数据库外键或级联删除，关联有效性由业务在同一个短事务中检查和维护。
• 现有迁移从 0001 到 0019，启动按顺序执行和记账；旧迁移保持不变。
• 实例数据目录有进程排他锁，防止两个控制器同时使用同一目录。
• 被引用的共享配置不能删除；有历史操作的项目不能作为普通草稿删除；操作使用的正文、凭据和程序副本不能按普通过期暂存回收。
• 数据库事务不长时间等待 SSH；文件发布、远端动作依靠独立记录和核对处理不完整状态。

这些规则在关联与事务约束 (line 36)和存储实现 (line 45)中有对应依据。

加密边界也需要分清：

• SSH 凭据、共享正文、项目正文及敏感快照使用应用层加密。
• 不是整个 SQLite 文件加密，普通业务元数据仍是普通记录。
• 程序及集中通用文件是磁盘上的实际字节，不属于正文密文存储。
• 主密钥丢失或与数据库不匹配会阻止正常解密和启动，没有换钥、重建入口。
• 登录 token 是可用访问凭据，保存在浏览器同源本地存储；退出只是清除本地副本。
• 应用只提供 HTTP，存储加密不等于传输加密。

详细边界见实例、认证与加密 (line 14)。

7. 限制、差异与待完成事项

已有能力的主要限制

Compose 和 systemd 的门槛是当前实现的接受条件，不是“这些版本和平台都已经经过真实环境验证”的支持矩阵。Compose 支持子集 (line 39)、systemd 支持边界 (line 16)

尚未实现的能力

这些未来行为仍有部分设计细节待完善，不能把原型演示直接视为全部交互已经确认。阶段顺序 (line 11)、巡检通知需求 (line 5)、FRP 边界 (line 3)、MySQL 复制边界 (line 5)

待验收与尚不能确认的事项

明确待验收：

• 第 4 阶段从首次部署到卸载、原位复用的整体体验与结果表达。
• 后加入的文件映射、集中目录、简化部署入口和列表三态筛选。
• 它们不能因为已合并，或第 3 阶段曾验收通过，就自动算本次增量已验收。

历史验证仍有边界：

• 真实 Docker/systemd 项目部署、更新、启停、卸载未验证。
• Debian 13 真实环境安装未验证；Ubuntu 实测不代表 Debian 也已实证。
• 文件映射那次浏览器验证受本地文件选择权限限制，上传取消与发布主要通过实际 HTTP 和组件测试覆盖。
• 其他架构、真实断电及其他文件系统不在已证实范围内。
• 页面重新聚焦后的鉴权行为，交付记录仍列有真实浏览器验证限制。

本次无法确认：

• 当前提交是否能重新构建、全部测试是否重新通过；
• 实时远端 Git、在线原型与用户实际运行版本；
• 任何真实服务器、配置或数据库当前状态。

以上均是未验证范围，不直接证明代码存在故障。

本次确认的文档与实现差异

对应证据：

• 旧状态说明：操作协议第 3 行 (line 3)、架构后端总述 (line 26)、前端映射说明 (line 47)；实际接入见应用组装 (line 140)。
• 配置字段：运行说明旧描述 (line 94)，对照当前映射保存 (line 138)。
• 程序副本：索引旧描述 (line 7)，对照0014 迁移 (line 33)。
• 删除条件：有效需求 (line 13)，对照所有项目均阻挡的查询 (line 118)和项目历史删除限制 (line 280)。
• 同机改址：有效需求 (line 14)，对照候选身份核验 (line 127)和保存复验及更新 (line 296)。

前四项是可直接确认的旧说明残留；后两项涉及需求与当前行为之间的边界，源码只能证明现状，不能据此改写用户决定。

另外，第 3 阶段验收文档中“第 4 阶段未启动”是当时验收范围的历史描述，不能和当前状态混读，也不应据此推翻已经发生的第 4 阶段实现。

8. 建议阅读顺序与下一步

适合项目所有者的阅读顺序

1. 先了解现在到哪里 读当前状态 (line 1)，再读交付记录中的验收表 (line 15)。先建立“已实现、历史验证、已验收”的区别。
2. 再了解日常怎么用 依次读运行说明 (line 46)、程序文件使用 (line 1)、项目草稿使用 (line 1)、项目部署与启停 (line 1)。
3. 确认产品边界 从需求目录 (line 1)按主题阅读，优先看管理对象、项目操作、配置与程序交付。涉及备份、FRP、复制时读对应边界，不从原型推断授权。
4. 深入理解执行与失败处理 读项目公共操作链 (line 1)，然后按需要读 Compose、systemd、变更、启停、卸载专题。这些比旧架构总述更接近当前实现。
5. 最后才看数据和接口细节 数据模型目录 (line 1)用于理解保存和关联；HTTP 接口目录 (line 1)用于核对前后端契约。它们不必作为首次了解项目的起点。

最值得你确认或验收的四件事

1. 完成第 4 阶段统一验收。 重点是 Compose 和 systemd 各走完整生命周期，并核对失败、部分完成、未知时的界面是否足够清楚。真实目标验证若要做，需要之后另行明确目标与范围。
2. 把最新映射和部署入口纳入验收。 特别看上传后保存/取消、共享映射采用、两字段创建后遇到阻断，以及浏览器实际文件选择路径。它们晚于原第 3 阶段验收。
3. 明确服务器退役与改址的两个边界。 全部项目卸载后是否允许删除连接；改址时是否必须在保存前核对原项目。当前实现与需求表述的落点不同，值得在真实使用前收口。
4. 后续单独同步滞后的总览说明。 当前状态和专题实现已较完整，但少数总览仍停留在早期阶段，会持续影响判断。修正文档应保留原验收记录的历史语境。

本次仅完成只读调查和报告：主仓库、原型均保持干净，没有创建分支、提交、推送、部署或启动任何实例，也没有产生需要清理的验证资源。上述建议不构成后续开发或第 5–7 阶段的执行授权。