107 lines
12 KiB
Markdown
107 lines
12 KiB
Markdown
# 原生 Shell 安装入口
|
||
|
||
这里直接维护 Bash 源码，由 Gitea 保存版本，Caddy 提供 HTTPS 下载。无需 Python 安装载荷。
|
||
已在实际 Caddy HTTPS 域名、一个测试宿主机和三个 Debian 13 VM 验证固定 release、Periphery/Core 接入、Docker 和 Headscale。Debian 12 升级与 SSH 管理密钥切换仍未真机验证；逐项证据在 platform 的验收记录中维护。
|
||
|
||
## Debian 13 接入 Komodo
|
||
|
||
以下命令以 root 执行。如果系统尚未安装 curl，或缺少 HTTPS 根证书，先安装下载所需的基础工具：
|
||
|
||
```bash
|
||
apt update && apt install -y curl ca-certificates
|
||
```
|
||
|
||
以下为域名占位示例；部署时替换为该环境的实际域名：
|
||
|
||
```bash
|
||
curl -fsSL 'https://scripts.example.com/releases/<40位小写Git提交>/install.sh' | bash -s -- \
|
||
--name prod-app-web-01 \
|
||
--core-url wss://komodo.example.com \
|
||
--core-public-key 'MCowBQYDK2VuAyEA<43个Base64字符>=' \
|
||
--assets-url 'https://scripts.example.com/releases/<40位小写Git提交>'
|
||
```
|
||
|
||
支持原生 systemd Debian 13 x86_64、Periphery/Core 2.3.4。Periphery 固定版本和 SHA-256；二进制只从 --assets-url 指定的 Caddy 下载，没有上游下载回退。
|
||
`--core-public-key` 是单行 X25519 SPKI 公钥的 Base64（固定前缀 `MCowBQYDK2VuAyEA`，结尾一个 `=`），不是 PEM，也不能带空格或换行。`--assets-url` 必须是 HTTPS `/releases/` 加 40 位小写提交；稳定入口不能直接作为安装资源基址。
|
||
脚本通过 apt 补齐 curl、jq、git、CA，配置 systemd，复用或生成节点身份，输出公开回执。
|
||
--check 做本地输入/身份检查，使用临时文件但不安装软件或修改主机配置；它不证明网络或 Core 状态。
|
||
回执在 /var/lib/platform-bootstrap/receipt.json，明确标记 Core 注册未验证、主机初始化未开始。
|
||
配置和身份在 `/etc/komodo/`，Periphery 的 Repo/Stack 工作目录在 `/var/lib/komodo/`。安装器的临时密钥材料使用受限临时目录并在退出时清除，服务日志交给 systemd journal。配置不符时停止，不自动迁移目录或创建兼容链接。
|
||
Docker、Headscale、公钥注入和安全配置后续由 Komodo 任务处理。没有 Core API 凭据下发。
|
||
已有身份、配置或二进制不符时停止，不自动替换身份。源文件可直接 bash install.sh --help。
|
||
|
||
`host-init.sh` 先检查基础包安装状态，仅在缺包时更新 APT 索引并补齐缺失包；已有完整基线的重跑不会无条件访问软件源。Docker 固定包仍须在执行前准备，构建与资源导入单独计时。
|
||
|
||
## 全服务器主机基线
|
||
|
||
`host-init.sh` 仅准备前置条件，不能作为完整主机基线验收。`--without-docker` 允许无容器角色只安装通用工具；不指定时沿用既有 Docker 契约。安装材料使用 root 受限的 `/var/tmp/platform-bootstrap/<批次>/`，不堆放 `/root`。
|
||
|
||
`host-baseline.sh --check --hostname NAME --release FULL_COMMIT` 输出逐项 JSON，本机差异返回 2。检查包括网络参数及持久配置、SSH、确认回执、防火墙、时钟同步、失败服务和待重启状态，另输出实际网卡队列、磁盘和安装残留信息；不等同于完整外部网络/存储/业务验收。
|
||
|
||
`--preflight` 检查内核模块与未知本地 sysctl 冲突；`--apply-network` 备份后仅设置 BBR 和默认 fq，失败恢复原值。不会替换活动 qdisc、清空未知配置或批量调整 conntrack/超时/内存。已有自定义文件必须先审查，不静默覆盖。
|
||
|
||
`ssh-access.sh --stage --hostname NAME --release FULL_COMMIT --key-sha256 SHA --firewall-sha256 SHA` 使用已由管理端验证的 root authorized_keys 摘要和目标防火墙渲染摘要，设置 61789、公钥认证和 root prohibit-password。仅用于已有确认防火墙的首次 SSH 标准化；复杂显式端口/Match/socket activation、自定义服务命令或环境停止并单独维护。先安排 240 秒回退及重启恢复，再修改配置；随后应用目标防火墙，apply/confirm 均传 `--ssh-transaction TRANSACTION`。从新 61789 SSH transport 先确认防火墙、再执行 SSH `--confirm --sha256 TRANSACTION`；配置输入、目标规则和实际规则必须与事务匹配。共享私钥不上传目标机。完整 Komodo 编排、外部确认入口、推广门禁与未实现项目见 platform 的 `docs/host-baseline.md`。
|
||
|
||
新增主机基线入口尚需真实 Debian 的 SSH/防火墙联合回退、重启恢复和完整验收；历史 Periphery 接入证据不能替代新入口的实机测试。
|
||
|
||
## Headscale 接入
|
||
|
||
`tailscale.sh` 使用显式版本、已准备的本地 DEB、SHA-256、HTTPS 控制端和节点名称。首次接入还需 root 所有、0600 权限的短期单次授权 key 文件；执行后清除临时 key 文件。既有 Running 节点直接复核身份，不需要新 key。
|
||
|
||
Headscale 0.29.6 从预授权 key 授予节点标签，拒绝预授权注册请求同时携带客户端 `--advertise-tags`。在控制端创建 key 时指定授权标签，`tailscale.sh --tags tag:ENV-ROLE,...` 必须核对接入后实际获得的完整标签集合。控制端、名称或标签不一致时停止，不重置节点身份。
|
||
|
||
跨主机服务直接使用 Headscale 分配的 `100.64.0.0/10`。脚本禁用接收子网路由及 Tailscale SSH；发现已有路由发布或出口节点选择时停止，不隐式撤销。公开网络回执保存到 `/var/lib/platform-bootstrap/tailnet.json`，包含节点 ID、公开 node key、IPv4、MagicDNS 与标签，先由控制端和 Headscale 核对，再填写集群端点并签发 TLS。重跑允许 node key 原生轮换，地址/ID/名称漂移要求单独维护。
|
||
|
||
## host 网络与防火墙
|
||
|
||
所有运行服务的 Docker 模板使用 host 网络，业务服务监听 `0.0.0.0`，由 Debian nftables 控制输入端口。`host-init.sh` 安装 nftables，不自动开放端口或替换现有防火墙。通过固定 release 的 `firewall.sh --check|--apply --policy /run/platform-secrets/firewall.json` 应用已登记的主机策略；文件必须为 root 0600，策略包含准确主机名、恢复 SSH 来源、公网端口和 Tailnet 来源/端口。
|
||
|
||
规则仅管理 `inet platform_host`，INPUT 默认拒绝公网未声明来源；本机回环、RFC1918（10/8、172.16/12、192.168/16）和 tailscale0 上的完整 100.64/10 默认允许所有端口/协议；不清空全局规则。`--apply` 安排 180 秒自动回退，从新的 SSH transport 验证后执行 `--confirm --sha256 <apply输出摘要>` 才持久化，并建立 Docker/Tailscale 的防火墙启动依赖。通过 sudo 确认时保留 `SSH_CONNECTION` 环境变量。详细 JSON 格式、端口矩阵、Headscale 标签关系与现有集群迁移约束在 platform 的 `docs/network.md`。
|
||
|
||
## 独立手工升级
|
||
|
||
```bash
|
||
curl -fsSL https://scripts.example.com/upgrade-debian12-13.sh | bash -s -- --check
|
||
curl -fsSL https://scripts.example.com/upgrade-debian12-13.sh | bash -s -- --upgrade
|
||
# 人工重启并重新登录后，继续原任务或验收：
|
||
bash upgrade-debian12-13.sh --resume
|
||
bash upgrade-debian12-13.sh --verify
|
||
```
|
||
|
||
resume/verify 可使用同一固定版本 URL 再次下载执行，或保存该版本的文件后执行。
|
||
默认升级使用真实终端 /dev/tty，APT 配置冲突由操作者判断。已经授权维护并确认救援入口时，可显式传 `--yes --recovery-confirmed`，使用非交互 APT 并保留本地配置；仍不自动重启、不自动 autoremove。升级和重启后的 resume 分别执行，不能并发运行。
|
||
|
||
官方 `deb-src` 和 Deb822 `Types: deb deb-src` 现在随二进制源一起校验和转换，不必临时禁用。BIOS/GPT 缺少 BIOS Boot 分区会在 check 阶段报错；已授权磁盘引导修复可给 upgrade/resume 增加 `--repair-bios-boot`。只自动处理 512 字节扇区、单个 Linux 分区从 2048 扇区开始、GPT first-lba 为 34 的已验证布局，在空闲 34–2047 扇区新增 BIOS Boot 分区。修改前备份 GPT 和磁盘首尾，修改后逐字校验原分区条目并重新安装 GRUB；其他布局停止，不移动或缩小已有分区。该选项不替代提供商救援入口和异机备份。
|
||
仅接受显式官方 Debian 源的受支持格式；第三方源、混合版本、复杂 Deb822 需先人工处理。
|
||
检查 APT、磁盘、UEFI 挂载；实际引导布局、救援入口和应用备份由操作者在升级前确认。
|
||
状态与系统归档在 /var/lib/platform-debian-upgrade；归档不替代异机或应用一致性备份。
|
||
|
||
## 发布
|
||
|
||
Caddy 同时提供 /install.sh 稳定入口与 /releases/<40位小写Git提交>/install.sh 固定版本入口；生产接入命令固定使用后者。
|
||
发布脚本只提取 `install.sh`、`upgrade-debian12-13.sh`、`host-init.sh`、`host-baseline.sh`、`ssh-access.sh`、`headscale-prepare.sh`、`tailscale.sh`、`firewall.sh`、README、artifacts.lock 及清单列出的 vendor 文件，生成 VERSION、SHA256SUMS；不暴露 .git 或工作区其他文件。上述入口全部必需，缺少任一文件就拒绝发布，不兼容缺少基线或防火墙入口的不完整文件集。
|
||
源代码与修复就在此仓库维护，无生成器、内嵌 Python 或第二份安装源码。
|
||
|
||
## 固定资源
|
||
|
||
`artifacts.lock` 是数据清单，每行三个制表符分隔字段：SHA-256、仓库内路径、准备时使用的上游 HTTPS URL。文件实际保存在 `vendor/<组件>/<版本>/<文件>`，与清单一同提交到 Gitea。目标机不读取上游 URL。
|
||
|
||
当前包含 Periphery 2.3.4 x86_64、Tailscale 1.104.4 amd64 DEB 和 PG 扩展构建资源，准确路径、摘要与来源见 `artifacts.lock`。控制端使用 platform 的 `control/vendor.sh --source <本仓库目录>` 准备资源，再用 `--check` 做完全离线校验。已有正确文件直接复用；摘要不符时停止，不静默覆盖。
|
||
|
||
新增版本时增加新路径和已核实摘要，准备二进制，同步修改 install.sh 的固定版本/摘要，检查后提交发布。不得改写已发布版本文件；固定提交及其 Caddy release 用于同版本回退。版本维护单独执行。
|
||
|
||
## Headscale 独立机准备
|
||
|
||
`headscale-prepare.sh` 在已登记并确认防火墙的 Debian 主机上校验主机名、端口及显式策略/DERP 文件，独占创建服务目录；相同输入重跑只复核，不清空 SQLite 或密钥。根目录的父目录须已存在。通过已发布固定 release 的 curl | bash 调用，参数见 `--help`。此入口不安装第二套控制面，不生成用户或授权 key；Headscale 与专用 Caddy 由 platform 的 `templates/headscale/standalone.toml` 部署。
|
||
|
||
|
||
## Headplane 准备与凭据
|
||
|
||
`headplane-prepare.sh --mode prepare|key --hostname NAME --root /srv/platform/headscale --port 3000 --project PROJECT` 在已有 Headscale 准备根目录内创建持久目录和独立 cookie，或按项目/服务标签和数据目录核对唯一健康 Headscale 容器后签发 90 天管理 key。凭据仅写 root 0600 文件，不输出值；重跑保留原值，未知或中断状态停止检查。Komodo Stack 负责服务启动，控制端回收凭据并验证登录。完整顺序见 platform 的 `docs/headscale-repeatable-install.md`。
|
||
|
||
|
||
Debian 初始化时，固定 release 的 `host-init.sh --apply` 支持 `--firewall-policy /run/platform-secrets/firewall.json --firewall-script /已校验的固定release/firewall.sh`，直接调用同一个防火墙事务。脚本不再另写一套内网规则。策略仍需明确主机名、现有 SSH 端口/公网恢复来源和公网服务端口；内网全部放行由通用 firewall.sh 自动生成。新建 SSH 验证后，用 apply 返回的准确摘要执行 firewall.sh --confirm。未传防火墙输入的旧调用仅准备包和主机名，不能宣称已完成防火墙初始化。
|
||
|
||
|
||
主机策略可增加 `trusted_sources: ["控制机实际公网IPv4"]`，对这些精确地址允许所有端口/协议。该字段由环境登记输入，禁止 CIDR，脚本不硬编码控制机 IP；host-init.sh 调用 firewall.sh 时自动使用同一字段。
|