104 lines
6.7 KiB
Markdown
104 lines
6.7 KiB
Markdown
# 跨设备接续入口
|
||
|
||
更新时间：2026-09-25。此文件用于在没有原聊天记录、没有原设备缓存的情况下接续开发。
|
||
这是开发交接，不是生产安装说明。新设备先阅读此文件，不要执行根 README 下方的旧部署脚本。
|
||
|
||
## 1. 获取正确分支
|
||
|
||
新架构已从 `codex/new-deployment-architecture` 合并到 `master`，用户已手动推送源码，
|
||
并授权提交、推送最新交接文档。**后续开发和跨设备接续统一使用 `master`。**
|
||
先为新设备配置仓库 SSH 权限，并从可信渠道核对 Git 服务器主机指纹；不要禁用主机校验。
|
||
|
||
新设备克隆：
|
||
|
||
```sh
|
||
git clone --branch master --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；获取远端分支后再切换。
|
||
|
||
```sh
|
||
git status --short
|
||
git fetch origin
|
||
git switch master
|
||
git pull --ff-only
|
||
```
|
||
|
||
若此前用 `--single-branch` 只克隆了工作分支，先运行
|
||
`git fetch origin refs/heads/master:refs/remotes/origin/master` 获取 master；
|
||
本地尚无 master 时，用 `git switch -c master --no-track origin/master` 创建分支，
|
||
再用 `git pull --ff-only origin master` 显式同步（避免旧单分支 fetch 配置影响跟踪关系）。
|
||
普通完整克隆可使用 `git switch --track origin/master`。
|
||
用 `git log -1 --oneline` 核对交接提交；旧工作分支只作历史参考。
|
||
有冲突或远端分叉时停止核对，不强制覆盖。跨设备轮换前，显式提交并推送本轮需要带走的文件。
|
||
聊天记录、本机临时文件和未提交修改不会随 Git 同步。
|
||
|
||
## 2. 阅读顺序与权威性
|
||
|
||
1. 本文件：当前停止点、待确认项与安全边界。
|
||
2. [实施状态](docs/implementation-status.md)：已完成工作包和实际验证证据。
|
||
3. [完整方案](docs/2026-09-25-complete-optimization-proposal.md)：已批准的总体架构。
|
||
4. [开发环境](docs/development.md)：新设备安装前提、构建与测试。
|
||
5. [CLI 协议](protocol/README.md)及所改模块的 `internal/<模块>/README.md`：接口与限制。
|
||
6. 需要远程工作时阅读[服务器初检](docs/2026-09-25-target-server-preflight.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 隔离细化方案待确认。
|
||
> 不执行旧部署脚本，不改服务器数据，不把校验结果当成安装授权；提交/推送按本轮用户要求处理。
|
||
|
||
后续每个工作包完成时更新本文件的停止点及实施状态；涉及协议、工具链或交付方式变化时同步开发指南。
|