跨设备接续入口

更新时间：2026-09-25。此文件用于在没有原聊天记录、没有原设备缓存的情况下接续开发。这是开发交接，不是生产安装说明。新设备先阅读此文件，不要执行根 README 下方的旧部署脚本。

1. 获取正确分支

用户已要求将 codex/new-deployment-architecture 合并到本地 master，后续本地开发以 master 为准。 本次明确只合并本地，未推送 origin/master。其他设备目前仍需拉取远端工作分支；只有后续获准推送 master 后，才能从远端 master 获取这些成果。 先为新设备配置仓库 SSH 权限，并从可信渠道核对 Git 服务器主机指纹；不要禁用主机校验。

远端 master 尚未同步时：

git clone --branch codex/new-deployment-architecture --single-branch ssh://git@git.joywaygames.cn:2222/joywaygamess/server-deploy.git
cd server-deploy
git branch --show-current
git log -1 --oneline
git status --short

已有本地仓库：先检查未提交更改，不要 reset、clean 或自动 stash；获取远端分支后再切换。

git status --short
git fetch origin
git switch codex/new-deployment-architecture
git pull --ff-only

若本地尚无该分支，用 git switch --track origin/codex/new-deployment-architecture 创建跟踪分支。 master 获准推送后，上述命令中的分支名改为 master；用 git log -1 --oneline 核对交接提交。有冲突或远端分叉时停止核对，不强制覆盖。跨设备轮换前，显式提交并推送本轮需要带走的文件。聊天记录、本机临时文件和未提交修改不会随 Git 同步。

2. 阅读顺序与权威性

本文件：当前停止点、待确认项与安全边界。
实施状态：已完成工作包和实际验证证据。
完整方案：已批准的总体架构。
开发环境：新设备安装前提、构建与测试。
CLI 协议及所改模块的 internal/<模块>/README.md：接口与限制。
需要远程工作时阅读服务器初检，并重新核对现场。

2026-09-24 的 Caddy/结构审查文档是历史讨论，不能覆盖已选定的 Traefik 方案。 docs/superpowers/plans/ 是各阶段计划，旧复选框不代表当前完成度；以实施状态和实际代码/测试为准。仓库不依赖某一 AI 工具的会话、记忆或个人技能目录才能开发。

3. 已确认架构与交付形式

为新服务器建设，不做旧服务器的数据迁移或旧脚本兼容；保留原有数据是最高约束。
应用可独立部署，数据库随应用隔离；公共环境为 Docker Compose、Traefik 等。
本地管理产品：React/TypeScript 页面 + Node 本地服务 + SQLite，经 SSH 调用远端 Go deployctl。
用户界面由浏览器打开；本地 API 只监听回环并需会话、Host/Origin、CSRF 防护。
不是已选定的 Electron/Tauri 桌面安装 App，也不是公网管理网站。
便携目标：Windows/macOS 解压启动，运行时随包交付，不要求最终用户安装开发工具。启动器、端口分配、数据目录、退出行为、签名和更新机制尚未实现/验收。
Apple 风格 UI；面板关闭不应影响已部署应用，已提交远端任务最终由 systemd 独立监督。后一项仍是未完成的设计目标。
claude-dev-stack 不纳入新体系；旧脚本暂留对照，不得作为新执行器的后端。

4. 当前完成与停止点

已完成八个基础工作包：离线计划、状态/锁、应用包完整性、受限 Compose 策略、本机预检、 dpkg 清单/版本锁、Docker 仓库签名认证、实际五个 Docker deb 的字节校验。

cmd/deployctl 和 internal/ 为当前实现。CLI 没有可用的安装、部署、升级、恢复写入口； executable 始终为 false。状态库尚未接入执行器。 apps/ops-panel/ 尚不存在；本地服务、UI、SSH 管理层、便携打包尚未交付。真实 deb 测试通过不等于完整依赖解析或安装验收。

下一工作包：Ubuntu 依赖源认证与隔离的完整 APT 依赖事务预演。最近提出的细化方案是：原生 APT 求解器、可信元数据/包状态快照、独立配置/缓存、不继承宿主钩子、只模拟；删除/降级/修改保留包或现场漂移时拒绝，输出完整变更清单。 该 APT 适配器细化方案尚待用户确认，尚未实现；本次跨设备交接不是对它的批准。 接续时先复跑基础测试，再请用户确认此边界，随后编写实施计划和失败测试。

5. 服务器与凭据边界

指定新服务器及已核对指纹见服务器初检文档；该文档是历史观察，不是当前现场保证。
截至本次交接，只完成该新服务器 SSH 只读初检；新执行器没有在那里安装/部署应用。
新架构阶段没有操作旧服务器；不要复用旧升级任务的授权去迁移或恢复数据。
新设备需要自行配置私钥或 SSH Agent、仓库访问权限和可信 known_hosts；均不通过 Git 交付。
私钥、有效密码、token、真实 .env、个人 SSH 配置、备份和数据库不能新增到提交中。 .gitignore 不会自动移除历史已跟踪的敏感文件；旧配置不得作为新部署输入。历史凭据轮换和 Git 历史清理需另行授权，不在本次交接范围。
claude-dev-stack/.env 的删除已按用户要求提交（f25f5df），并包含在本地 master 中，不恢复它。不以合并为由擅自清理其余旧目录；Git 历史仍可能含旧配置，不要使用或复制其中凭据。
远端写入前重新核对主机身份、数据/服务、容量和影响，并取得具体操作授权。不做整机升级、不重置防火墙、不删除卷/数据库、不把备份恢复覆盖到原数据。

6. 可直接交给接续助手的说明

请先阅读 HANDOFF.md、docs/development.md、docs/implementation-status.md 和已批准的完整方案。检查实际分支和 git status，保留用户修改，在当前目录接续，不依赖旧聊天或其他设备的绝对路径。先构建并运行本机测试，区分历史证据与本次结果。当前停在第八工作包之后，APT 隔离细化方案待确认。不执行旧部署脚本，不改服务器数据，不把校验结果当成安装授权；提交/推送按本轮用户要求处理。

后续每个工作包完成时更新本文件的停止点及实施状态；涉及协议、工具链或交付方式变化时同步开发指南。

6.6 KiB Raw Blame History