# offline-dev-deploy

**Repository Path**: csc105/offline-dev-deploy

## Basic Information

- **Project Name**: offline-dev-deploy
- **Description**: 内部开发环境初始化与部署自动化仓库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# offline-dev-deploy

内部离线开发环境的部署与运维工具包：提供可重建的 Docker Compose 模板、主机部署脚本、服务专属部署资产、systemd 单元占位镜像、脱敏配置示例和按 Diátaxis 组织的文档，用于环境的部署、验证、日常维护和故障恢复。仓库服务于一套内网开发环境，不承担生产配置管理、凭证保管或备份存储职责。

大模型网关（LLM Gateway）的源码是上游独立仓库
[fuselia-llm-gateway](https://gitee.com/gitee-lsvvy/fuselia-llm-gateway)；本仓库负责把它部署到
汇聚节点（小主机）并维护接入约束，见
[准备本地大模型网关](docs/how-to/prepare-llm-gateway.md)。

## 系统总览

环境由接入终端、汇聚节点（小主机）、算力节点（DGX ×2）和供电保护（UPS）组成，网络按用途划分为业务、算力、设备管理、控制四类网段：业务数据从业务网段的各服务进出，控制数据收敛于控制网段，跨段访问一律经小主机上的应用入口完成。详细说明见[内部开发环境架构](docs/explanations/architecture.md)。

```mermaid
flowchart TB
    UPS["UPS"]

    subgraph TERM["接入终端（电脑）"]
        DEV["开发终端"]
        ADMIN["管理终端"]
    end

    subgraph MINHOST["小主机：设备接入与数据汇聚"]
        BUSINESS["业务服务<br/>代码 / 文档 / 镜像 / 远程协作"]
        GATEWAY["LLM Gateway<br/>业务网统一模型入口"]
        PRIMARY["NUT Primary<br/>读取 UPS 状态并发布 FSD"]
        MONITOR["监控与日志"]
    end

    subgraph DGX["DGX 算力节点"]
        DGX1["DGX1 head<br/>分布式模型入口 + NUT Secondary"]
        DGX2["DGX2 worker<br/>分布式计算 + NUT Secondary"]
    end

    DEV -->|"业务网"| BUSINESS
    DEV -->|"模型请求"| GATEWAY
    GATEWAY -->|"算力网：head API"| DGX1
    DGX1 <--> DGX2

    UPS -->|"UPS 网：SNMP"| PRIMARY
    PRIMARY -->|"控制网：NUT / FSD"| DGX1
    PRIMARY -->|"控制网：NUT / FSD"| DGX2
    DGX1 -->|"控制网：日志 / 指标"| MONITOR
    DGX2 -->|"控制网：日志 / 指标"| MONITOR
    ADMIN -->|"控制网"| MONITOR

    linkStyle 0,1 stroke:#0369A1,stroke-width:3.5px
    linkStyle 2,3 stroke:#7C3AED,stroke-width:2px
    linkStyle 4 stroke:#C2410C,stroke-width:2px
    linkStyle 5,6,7,8,9 stroke:#16A34A,stroke-width:3.5px
```

小主机是设备接入、协议适配和数据汇聚节点，不是通用 IP 路由器。图中以物理主机为框，连线颜色对应所走网段：蓝=业务网段、紫=算力网段、橙=UPS 网（设备管理段）、绿=控制网段，网段名同时标注在连线上；业务网段与控制网段加粗突出。各网段地址、端口与隔离矩阵统一见[网络地址、端口与隔离矩阵](docs/reference/network-address-port-matrix.md)。

## 快速开始（部署）

完整流程见[部署总览](docs/tutorials/deployment-overview.md)；逐项手动方式见[分步部署](docs/tutorials/manual-deployment.md)。下面是一键路径的执行顺序（所有命令从仓库根目录执行）：

```bash
git clone https://gitee.com/gitee-lsvvy/offline-dev-deploy.git
cd offline-dev-deploy
```

**第 0 步：准备 profile（各目标机共用一份）**

```bash
cp configs/offline-dev.env.example /etc/offline-dev/offline-dev.env
# 编辑：各网段 IP、网卡名、NUT 密码、各 *_BIND_IP/*_PORT、模型脚本路径等
```

如果不想自己编辑，可以使用如下方法进行一键到位：

```bash
sudo bash scripts/deploy/coldstart-minhost.sh
```

详见[准备部署配置](docs/how-to/prepare-deployment-configuration.md)。整机
重装后的新机还需三项冷启动预备（上传仓库到目标机、预写 Docker 镜像加速、
预建 docker 组），见[一键部署](docs/tutorials/one-click-deployment.md)的
"新机冷启动预备"。

**第 1 步：一键部署小主机**（业务 12 容器 + LLM Gateway + NUT Primary）

```bash
sudo OFFLINE_DEV_CONFIG=/etc/offline-dev/offline-dev.env \
  bash scripts/deploy/bootstrap-minhost.sh --dry-run       # 预演
sudo OFFLINE_DEV_CONFIG=/etc/offline-dev/offline-dev.env \
  bash scripts/deploy/bootstrap-minhost.sh --apply-network  # 正式（维护窗口）
```

**第 2 步：一键部署 DGX1 / DGX2**（`DGX_ROLE` 区分角色，dgx1 = head）

```bash
sudo OFFLINE_DEV_CONFIG=/etc/offline-dev/offline-dev.env DGX_ROLE="dgx1" \
  bash scripts/deploy/bootstrap-dgx.sh --apply-network
# DGX2 用 DGX_ROLE="dgx2" 执行相同命令
```

DGX1 会额外安装 `dgx-model-ensure.service`（模型开机自启，见
[模型开机、关机与日常管理](docs/how-to/model-power-and-lifecycle.md)）。

**第 3 步：配置自愈免密 SSH（各一条）**

```bash
# 小主机 → DGX1：开机自愈 check-dgx-model 需要
ssh-copy-id nvidia@${DGX1_CONTROL_IP}
# DGX1 → DGX2：模型自启 / start.sh 远程拉起 worker 需要
ssh-copy-id nvidia@${DGX2_COMPUTE_IP}
```

**第 4 步：放置模型（DGX1，一次性）**

把模型目录（含官方 `start.sh` / `stop.sh` 与 `.env`）放到 profile 中
`DGX1_MODEL_START_SCRIPT` 声明的路径，并手动启动一次确认健康。

**第 5 步：端到端验收**

```bash
bash scripts/verify/verify-all.sh                       # 小主机汇总检查，应 FAIL=0
curl http://192.168.90.200:8000/v1/models               # 网关 OK（地址以 profile 为准）
curl http://192.168.90.200:8001/v1/models               # nginx 透传 OK
```

部署后的接入对象还包括开发机和管理机（各有接入与自检入口，见下表）。验收清单与断电联动演练见[服务验证清单](docs/reference/service-verification-checklist.md)和[断电联动测试与复位](docs/how-to/power-failure-test-and-reset.md)。

## 日常使用入口

> 服务地址已支持内网域名（`*.off.internal`，与 IP 等价）。**要用域名的每台机器（开发机/管理机）都需手动配置一次 DNS：把网卡的 DNS 服务器指向小主机 `192.168.90.200`**（各系统具体步骤见[内网 DNS 使用指南](docs/how-to/internal-dns.md)第 3 节）；未配置的机器功能不受影响，继续走 IP 即可。域名表、代理绕过与排障见同一指南。

| 你是谁 | 想做什么 | 入口 |
| --- | --- | --- |
| 管理员 | 部署/重建环境 | [部署总览](docs/tutorials/deployment-overview.md)、[一键部署](docs/tutorials/one-click-deployment.md) |
| 管理员 | 启停/排查大模型 | [模型开机、关机与日常管理](docs/how-to/model-power-and-lifecycle.md) |
| 管理员 | 监控、SSH 巡检、断电演练 | [管理机部署](docs/tutorials/administrator-workstation-deployment.md)、[Grafana 监控使用指南](docs/how-to/grafana-monitoring-usage.md) |
| 管理员 | 数据备份与恢复 | [Borg 备份与恢复](docs/how-to/borg-backup-and-restore.md)、[备份与恢复策略](docs/explanations/backup-strategy.md) |
| 开发成员 | 第一次接入环境 | [新成员入职第一天](docs/tutorials/new-member-day-one.md) |
| 开发成员 | 使用代码/文档/镜像/模型/远程协助/内网源 | [开发机服务](docs/how-to/development-services.md) |
| 开发成员 | 代码托管（账号、建仓、克隆与协作） | [Gitea 代码托管](docs/how-to/gitea-code-hosting.md) |
| 任何人 | 排查故障 | [常见问题排查](docs/reference/troubleshooting.md) |
| 任何人 | 理解架构与设计 | [文档索引](docs/README.md) |

## 仓库结构

| 路径 | 内容 |
| --- | --- |
| [`configs/`](configs/) | 主机 profile 模板等脱敏配置示例 |
| [`services/`](services/README.md) | 服务专属资产：`minhost/`（小主机业务与监控 Compose 源模板、监控配置、开机单元占位镜像）、`dgx/`（`model/` 模型自启/自愈脚本与占位 unit、`obs/` 观测栈模板与占位 unit）、`nut/`（NUT 模板与部署脚本）、`llm-gateway/`（网关部署与运行脚本）、`borg-backup/`（borgmatic 增量备份到外接备用盘：Compose 模板与运维脚本） |
| [`scripts/`](scripts/) | 主机级编排：网络、引导部署、运行时同步和验证脚本 |
| [`docs/`](docs/README.md) | 按 Diátaxis 组织的教程、操作指南、参考和架构解释 |
| [`docs/diagrams/`](docs/diagrams/README.md) | Mermaid 图风格档案（网段语义色等） |
| [`.repository/`](.repository/standards/) | 外部规范源完整快照（fuselia-infra-repository，见[仓库规范来源](docs/repository-standards.md)） |
| [`skills/`](skills/) | 随仓库交付的 Agent Skill（`repo-standards` 规范检查、`documentation`、`mermaid-diagrams`） |
| [`LICENSE`](LICENSE) | 本仓库自身 MIT 许可证（内嵌规范源快照与第三方 Skill 按各自许可分发） |

Git 中仅跟踪配置示例。实际配置按用途放在 `/etc/offline-dev/offline-dev.env`、Compose 运行目录 `.env` 或 `/etc/nut/`，由部署脚本、Compose 或 NUT 服务加载；不要把运行时文件复制回仓库维护。服务监听地址和端口使用各服务独立的 `*_BIND_IP`、`*_PORT` 参数，示例中的地址只是默认 profile。

仓库不包含：生产密码、私钥、Token、完整 `.env`；运行数据、Clonezilla 镜像、Docker 镜像包和模型权重。事故与迁移过程记录放 `docs/reference/` 并标注是否仍然有效。

## 已知缺口

- **DGX 自动化范围**：模型权重的分发与放置仍在 DGX1 手工执行；如需小主机统一编排，必须先定义受限 SSH 部署凭证、回退策略和禁止远程电源操作的边界；
- **网关接口契约**：流式超时与并发上限边界值仍需压测（版本谱系警示见[网关准备指南](docs/how-to/prepare-llm-gateway.md)）；
- **head/worker 生命周期**：待补异常中断后的自动重试策略与仅 DGX2 单机重启的重建自动化；
- **网络强制隔离**：完成并记录 `ip_forward=0` 的实际验证；需要强隔离时将逻辑分区升级为 VLAN/ACL 或防火墙策略；
- **最终验收记录**："两台 DGX 通过 NUT Secondary 各自完成本机关机"的断电演练仍待维护窗口执行；
- **自动化资源基线**：补充实际采用的 APT 源、镜像归档、Compose 插件下载地址、Gateway 源码提交和各资源 SHA256。

## 维护与贡献

修改 `scripts/`、`services/` 或 `configs/` 后，同步检查相关教程、操作指南、参考表和索引。提交前运行适用检查：

```bash
git diff --check
find scripts services -type f -name '*.sh' -print0 | xargs -0 -n1 bash -n
docker compose --env-file services/minhost/.env.example \
  -f services/minhost/docker-compose.yml config -q
```

上述检查只验证模板和语法，不代表真实设备已经部署成功。分支、提交约定和评审流程见[贡献指南](CONTRIBUTING.md)；Agent 维护边界与规范检查入口见 [`AGENTS.md`](AGENTS.md)；采用的规范来源与版本记录见[仓库规范来源](docs/repository-standards.md)。