HostShift

 # HostShift HostShift 提供确定性的 Ubuntu 和 Debian 服务器迁移，具备可审计的规划和验证功能。 HostShift 通过 SSH 发现活动服务器，构建可审查的迁移配置文件，准备干净的目标服务器，传输数据，并验证结果。它强制执行严格的只读源策略：不进行源端写入，不使用 `sudo`，不重启服务，不安装软件包，不更改防火墙规则，不添加密钥，不创建快照，不进入维护模式。 [文档](https://hostshift.karacabay.com) | [安装](#安装) | [AI 集成](#AI-集成) | [您获得的功能](#您获得的功能) | [工作原理](#工作原理) | [验证](#验证) | [安全模型](#安全模型) --- HostShift 是一个 CLI-first 迁移工具和 Codex 插件，用于实际的 Linux 网络栈迁移。它适用于您在 Ubuntu 或 Debian 主机上运行生产服务，需要在其他地方重现这些服务，而停止或修改源服务器是不可接受的情况。 迁移引擎是确定性的 Go 代码。Codex 插件是一个操作层，帮助 Codex 遵循工作流程，保持源只读合同，并运行正确的 `hostshift` 命令。 ## 之前 / 之后 手动服务器迁移： > 手动检查服务，复制配置文件，猜测软件包名称，转储数据库，追踪缺失的防火墙规则，遗忘 SSH 设置，在压力下重试，希望源服务器仍然正常运行。 HostShift 迁移： ```bash hostshift discover --source old-server --name rehearsal --profile rehearsal.profile.yaml --json hostshift plan --profile rehearsal.profile.yaml --target new-server --json hostshift explain --profile rehearsal.profile.yaml --target new-server --json hostshift prepare --profile rehearsal.profile.yaml --target new-server --json hostshift sync --profile rehearsal.profile.yaml --target new-server --json hostshift verify --profile rehearsal.profile.yaml --target new-server --json ``` 相同的目标。更少的猜测。源服务器保持只读。 ```text 源服务器变异策略 被阻止 目标服务器变异策略 计划和可审查 传输路径 通过 SSH 流式传输 配置文件格式 YAML + JSON 架构 验证 工作负载检查，非人工检查 恢复/审计 状态 + JSONL 日志 ``` ## 安装 使用发布二进制文件进行迁移演练和生产工作。完整的发布验证位于 [docs/install.md](./docs/install.md)。 ```bash tar xzf hostshift_<version>_<os>_<arch>.tar.gz install -m 0755 hostshift /usr/local/bin/hostshift hostshift version ``` 从源代码构建： ```bash git clone https://github.com/oguzhankrcb/HostShift.git cd HostShift make build ./dist/hostshift version ``` 直接从源代码运行： ```bash go run ./cmd/hostshift version go run ./cmd/hostshift doctor --source old-server --target new-server --json go run ./cmd/hostshift discover --source old-server --name example --profile example.profile.yaml --json go run ./cmd/hostshift plan --profile examples/profile.yaml --target new-server --json go run ./cmd/hostshift explain --profile examples/profile.yaml --target new-server --json go run ./cmd/hostshift prepare --profile examples/profile.yaml --target new-server --json go run ./cmd/hostshift sync --profile examples/profile.yaml --target new-server --json go run ./cmd/hostshift verify --profile examples/profile.yaml --target new-server --json go run ./cmd/hostshift profile migrate --input examples/profile.yaml --output /tmp/profile.v2.json ``` 使用已安装的二进制文件，替换 `go run ./cmd/hostshift` 为 `hostshift`。 > [!IMPORTANT] > `prepare`、`sync` 和 `verify` 默认处于 dry-run 模式并写入可恢复状态。仅在审查阻止器、操作、流和回滚元数据后添加 `--apply`。 ## Codex 插件 HostShift 作为 Codex 插件随 [plugins/hostshift](./plugins/hostshift) 一起提供。该插件不会替换 CLI。它为 Codex 提供迁移工作流程、安全规则和操作指南，而确定性的 `hostshift` 二进制文件执行发现、规划、传输和验证。 从此存储库市场安装： ```bash codex plugin marketplace add https://github.com/oguzhankrcb/HostShift.git codex plugin add hostshift@hostshift ``` 从检出进行本地开发： ```bash codex plugin marketplace add . codex plugin add hostshift@hostshift ``` 安装或更新插件后启动新的 Codex 线程，以便加载捆绑的 `migrate-server` 技能。 ## AI 集成 HostShift 将 AI 集成作为 Go CLI 周围的操作层公开： - Codex 插件：`plugins/hostshift` - MCP stdio 服务器：`hostshift mcp stdio` - Claude Desktop 示例：[integrations/claude/claude_desktop_config.example.json](./integrations/claude/claude_desktop_config.example.json) 验证 MCP 和 Claude 集成界面： ```bash hostshift mcp doctor --json hostshift capabilities --json ``` MCP 工具故意非应用：它们可以运行发现、规划、AI 友好解释、结构化审查、dry-runs、切换 dry-runs、配置文件迁移、源策略内省、功能目录检查和回滚元数据。MCP 服务器还公开了 `hostshift_migration_operator` 提示和 `hostshift://source-safety`、`hostshift://migration-workflow` 和 `hostshift://capabilities` 资源，以便 Claude 或其他客户端可以直接加载安全工作流程。目标变异仍然需要审查的人工 CLI 命令。 ## 支持的平台 第一个支持矩阵专注于当前的 Ubuntu 和 Debian 服务器目标。 | 家族 | 支持的版本 | | --- | --- | | Ubuntu | 22.04 LTS, 24.04 LTS, 25.10 interim, 26.04 LTS | | Debian | 12, 13 | 默认情况下，EOL 目标被阻止。EOL 源仍然可以在迁移保持源安全的情况下被读取。源和目标版本不需要匹配；HostShift 检查平台功能而不是假设相同的镜像。 ## 您获得的功能 | 领域 | HostShift 执行的操作 | | --- | --- | | 源发现 | 通过允许的命令读取 OS、软件包、服务、Docker、Web 服务器、SSH、防火墙和数据库事实。 | | 配置文件 | 编写具有 JSON 架构验证、工作负载元数据、检查、目标设置和机密环境变量引用的 v2 YAML 配置文件。 | | 规划 | 在应用前发出可审查的 `Action{id, phase, hostRole, impact, command, preconditions, rollback}` 记录。 | | 目标准备 | 计划目标软件包安装和 Docker、数据库、Nginx/Apache、SSH、UFW、nftables 和应用依赖项的配置文件写入。 | | 传输 | 从源 stdout 流式传输文件、容器镜像、MySQL/MariaDB 和 PostgreSQL 到目标 stdin。 | | 验证 | 检查 HTTP、Laravel 数据库连接、文件、DB 标量查询、systemd 服务、防火墙规则、nftables 和 Nginx 配置。 | | 状态 | 保持可恢复的运行状态和 JSONL 审计日志。 | | 安全 | 在代码和测试中阻止源端变异尝试。 | 参见 [examples/profile.v2.yaml](./examples/profile.v2.yaml) 和 [examples/web-stack-v2.yaml](./examples/web-stack-v2.yaml) 以获取实际配置文件形状。 ## 工作负载 当前工作负载覆盖范围包括： - Docker Compose 项目 - 独立的 Docker 容器 - 通过显式快照、一次性、数据库支持或外部策略的 Docker 命名卷 - 绑定安装的文件集 - 流式 Docker 镜像 - MySQL 和 MariaDB - PostgreSQL - 通过现有的 RDB 快照或只读副本流的 Redis - Nginx 配置和重载验证 - Apache vhost 激活和重载验证 - Caddy 配置和重载验证 - systemd 应用服务切换和服务检查 - cron 文件传输、目标 cron 软件包规划和目标 cron 重载 - PHP-FPM 配置传输、目标软件包规划和目标服务重载 - Supervisor 配置传输、目标软件包规划和目标重新读取/更新 - Fail2ban 配置传输、目标软件包规划和目标服务重载 - Memcached 配置传输、目标软件包规划和目标服务重启 - RabbitMQ 配置传输、目标软件包规划和目标诊断；活动队列/消息不迁移 - Certbot/Let's Encrypt 状态传输、目标软件包规划、证书列表和当可用时的续期计时器激活 - Logrotate 配置传输、目标软件包规划和目标配置验证 - SSH 服务器设置 - UFW 和 nftables 防火墙规则 - Laravel 样式的数据库连接检查 除非配置文件命名现有的 RDB 快照或只读副本端点，否则 Redis 工作负载被阻止。HostShift 从不运行源端 `SAVE`、`BGSAVE` 或 Redis 配置更改。发现的 Docker 命名卷是阻止器，直到配置文件显式选择 `snapshot`、`disposable`、`database-backed` 或 `external`。`snapshot` 策略读取源上已存在的 tar 文件，并将其提取到审查的目标路径；HostShift 从不创建源端卷快照。 ## 工作原理 1. **医生** 检查连接性、平台支持和明显的阻止器。 2. **发现** 通过允许的只读操作读取源事实。 3. **配置文件** 记录工作负载、目标配置、检查和环境变量机密引用。 4. **计划** 将配置文件转换为可审查的操作和流。 5. **解释** 总结阻止器、警告、流、目标影响和安全下一步行动，供 AI 辅助审查。 6. **审查** 发出结构化发现、工作负载感知建议、建议的 YAML 片段、操作员检查清单和 AI 安全简报。 7. **准备** 在批准后应用目标软件包和配置更改。 8. **同步** 从源 stdout 流式传输数据到目标写入。 9. **验证** 运行目标检查并记录审计输出。 10. **切换** 运行审查的目标启动操作，例如 Compose `up` 或独立容器 `run`。 11. **回滚/状态/恢复** 报告目标回滚元数据并继续从状态中断的运行。 同步计划可能包括诸如 `tar --create -> tar --extract`、`existing Docker volume snapshot tar cat -> tar --extract`、`docker image save -> docker image load`、`mysqldump -> mysql` 和 `pg_dump -> pg_restore` 等流。源端产生 stdout；目标端仅变异目标。 中断的应用运行可以被检查和恢复，而无需重放已完成的步骤： ```bash hostshift status --state-dir .hostshift --run-id sync-001 --json hostshift resume --profile migration.profile.yaml --state-dir .hostshift --run-id sync-001 --json hostshift resume --profile migration.profile.yaml --state-dir .hostshift --run-id sync-001 --apply --json ``` 状态以原子方式写入每个已完成操作或流后，并且每个运行的操作系统锁防止并发应用进程重放相同的操作。恢复如果配置文件、目标、阻止器或生成的命令不再匹配保存的计划指纹，则拒绝运行。如果中断的命令可能部分更改了目标，则应用在操作员明确命名它时保持阻塞，直到 `--retry-failed <action-id>`。 ## 验证 快速检查： ```bash make test make test-go make build npm run docs:build npm run docs:compose:config ``` Docker 迁移矩阵： ```bash make test-integration-docker HOSTSHIFT_RUN_DOCKER_MATRIX=1 make test-integration-docker ``` 真实 VM 端到端： ```bash make test-e2e-vm HOSTSHIFT_RUN_VM_E2E=1 make test-e2e-vm make build HOSTSHIFT_RUN_VM_E2E=1 bash tests/e2e/vm/run-vm-e2e.sh --pair 'ubuntu22->debian12' --apply ``` Docker 矩阵运行 SSH 驱动的源/目标容器。VM 端到端层启动真实的 Lima 实例，捕获源快照，通过 SSH 运行 `discover`、`plan`、`prepare`、`sync` 和 `verify`，验证工作负载一致性，重启目标，验证持久性，并检查源快照是否未更改。 发布候选版本必须满足 [docs/validation.md](./docs/validation.md) 中的关卡，包括源不变性、跨发行版 Docker 覆盖、真实 VM 应用覆盖、校验和和 SBOM 输出。 ## 安全模型 HostShift 的核心不变性是严格的： > 源服务器是一个不可变的观察端点。 源上允许： - 读取库存 - 检查配置 - 流式传输类型导出到 stdout - 运行允许的事实命令 源上禁止： - `sudo` - 写入文件 - 安装软件包 - 重启或停止服务 - 更改防火墙规则 - 添加 SSH 密钥 - 创建快照 - 将应用放入维护模式 - 在磁盘上创建数据库转储文件 已知限制被报告而不是隐藏。实时文件系统流式传输不是一个时间点快照。MySQL 转储可以获取元数据锁。PostgreSQL 转储根据所选数据库一致，而不是跨无关数据库。无法安全读取的工作负载是阻止器，而不是静默跳过。 ## 文档 文档网站发布在 [hostshift.karacabay.com](https://hostshift.karacabay.com)。如果您更喜欢完整的指南格式，请点击那里获取安装、配置文件、工作负载、验证和参考页。 站点源代码在 [docs-site](./docs-site) 下使用 Astro Starlight 构建。 ```bash cd docs-site npm install npm run dev ``` 或使用 Docker Compose 运行： ```bash docker compose -f docs-site/compose.yml up --build ``` 打开 `http://localhost:4321`。 有用的文档： - [安装](./docs/install.md) - [架构](./docs/architecture.md) - [威胁模型](./docs/threat-model.md) - [验证](./docs/validation.md) - [发布检查清单](./docs/release.md) - [安全策略](./SECURITY.md) - [贡献](./CONTRIBUTING.md) ## 发布 ```bash make release-snapshot make checksum make sbom ``` `make release-snapshot` 在安装了 GoReleaser 时使用。没有 GoReleaser，它仍然会构建 `dist/hostshift`，写入 `dist/checksums.txt`，并从 Go 模块图生成 `dist/hostshift.sbom.spdx.json`。 SBOM 生成在 Go CLI 中实现： ```bash hostshift sbom --output dist/hostshift.sbom.spdx.json --json ``` 在公开标记之前，请完成 [docs/release.md](./docs/release.md)：托管 CI 候选版本、自托管或本地 VM 应用、干净的工作树和签名的校验和验证。 ## 状态 HostShift 处于验证里程碑。Go `hostshift` CLI 是用于发现、规划、传输、验证、切换和回滚的实现。云和 DNS 自动化故意在核心之外。 ## 许可证 Apache-2.0。参见 [LICENSE](./LICENSE)。