# digital-center-deployer

**Repository Path**: pwginfo/digital-center-deployer

## Basic Information

- **Project Name**: digital-center-deployer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Digital Center Deployer · 数字中心部署系统

一个**中心(core) — 多客户端(client)** 的分布式部署/调度系统。

> `center` 是实现于 `deploy-server` 中的唯一权威中心；`web` 与 `client` 都只与
> center 交互。一次只部署一个中心，但可以有**多个 client 实例**；中心对多客户端
> 做**负载均衡**调度，并负责把项目部署任务分发给各 client，由 client 在本机完成
> Docker 构建与运行。server 层本身设计为无状态，未来可横向扩展做负载均衡。

## 架构总览

```
                    ┌──────────────────────────────────────────────┐
   ［Web 管理台］   │         deploy-server  (Center 中心)          │
  ┌──────────────┐  │  FastAPI · SQLite · 线程隔离全局缓存          │
  │  deploy-web  │◀─┼─ REST ─┐                                      │
  │Vue3+TS+EPlus │  │        │    ┌─────────────┐   ┌─────────────┐ │
  └──────────────┘  │        ▼    │ClientRegistry│──▶│LoadBalancer │ │
                    │   ┌──────┐ │ (在线/负载)  │   │轮询/最少连接 │ │
  ［客户端实例］    │   │ 项目 │ └─────────────┘   └─────────────┘ │
  ┌──────────────┐  │   │ 任务 │        │                          │
  │ deploy-client│◀─┼─ REST/心跳 ┐    ▼ 指派目标                   │
  │  Python SDK  │  │            │  多客户端（在线列表）            │
  │  + Docker 执行│  │            │                                 │
  ├──────────────┤  │            └─────────────────────────────────┘
  │ 更多 client   │               ▼  数据库 SQLite
  └──────────────┘        (clients / client_configs / projects / tasks)
```

- **center 与 web**：Web 管理台通过 REST 调用中心（健康/客户端/任务/项目/配置），并经中心派单；
- **center 与 client**：client 向中心注册（上报探活地址、支持能力、本机配置）→ 心跳保活 →
  中心按负载均衡策略把任务指派给某个在线 client → client 执行后回执结果；
- **client 部署执行**：client 内置 Docker 能力，接收中心下发的项目声明，在本机生成
  Dockerfile、拉取/解压源码、`docker build` 并 `docker run`，把容器状态回写中心；
- **server 负载均衡**：中心内置 `轮询 / 最少连接` 两种策略；中心自身无状态，多实例
  可挂负载均衡网关进行扩展。

## 核心能力

| 能力 | 说明 |
|---|---|
| 客户端管理 | 注册/心跳/列表/详情，状态由 **URL 主动探活**动态推导（可达即在线） |
| 部署方式（模板） | **程序内置、自动注册**，全局共享，按 client 上报的支持范围过滤展示 |
| 客户端本机配置 | 每台 client 的部署环境（数据/部署根目录、镜像源、网络、资源上限）存 DB、中心可编辑、下发到 client |
| 项目部署 | git 拉取 / 中心上传源码 → 生成 Dockerfile → build → run → 状态回写 |
| 负载均衡 | 轮询 / 最少连接两种策略 |
| 多客户端演示 | `cli.main demo` 本机模拟多客户端 + 批量派单 |

## 配置分层模型（中心声明式 + client 本机适配）

系统刻意把「部署什么」与「在哪台机器怎么跑」分开：

```
模板默认（程序内置）──merge──► 项目覆盖 ──► 声明式 spec（平台无关）
                                                 │
client 本机配置（存 DB、中心编辑、随心跳下发）────┴──► 解析为具体宿主命令
```

- **中心只发平台无关的声明**，绝不出现 `/opt`、`D:\` 这类宿主绝对路径，也不假设 OS；
- **client 负责本机适配**：把抽象声明解析成自己机器上的具体动作。

| 声明（中心 / 项目） | 本机解析（client） |
|---|---|
| `deploy_subpath`（相对子路径） | 部署目录 = `deploy_root + deploy_subpath` |
| 卷 `{name, container, mode}` | 宿主路径 = `data_root/项目/卷名` |
| 网络名（可为空） | 项目声明 ‖ 本机默认网络 ‖ bridge |
| 资源请求 `{cpu, memory}` | `min(请求, 本机上限)` |
| `registry_mirror` | 构建时给基础镜像加前缀 |
| `restart_policy` / `health_check` / `labels` | 直接映射为 `docker run` 参数 |

**部署方式（模板）** 内置两种，新增方式只需在两端各登记一处：

| key | 名称 | 基础镜像 | 构建 | 运行 |
|---|---|---|---|---|
| `java` | Java 项目 | `eclipse-temurin:17-jdk` | `mvn -q clean package -DskipTests` | `java -jar target/*.jar` |
| `web-node` | Web 前端 | `node:20-alpine` | `npm ci && npm run build` | `npm run start` |

- center 端：`deploy-server/app/services/deployments.py`（模板元信息）；
- client 端：`deploy-client/client/deploy.py` 的 `_TEMPLATES`（Dockerfile 生成器）。

## 技术选型

| 层 | 选型 |
|---|---|
| 后端中心 | Python + FastAPI |
| 前端 | Vue 3 + TypeScript + Element Plus + Vite |
| 数据库 | SQLite（单文件、零外部服务） |
| 客户端 | Python（stdlib HTTP 服务 + httpx）+ Docker CLI |
| 缓存 | 自研全局缓存类（线程隔离 / asyncio 任务隔离，零依赖），可选 `cachetools` |

## 目录结构

```
digital-center-deployer/
├── deploy-server/   # Center 中心服务（FastAPI + SQLite + 缓存 + 部署模板）
├── deploy-client/   # 客户端 SDK + CLI（注册/心跳/任务 + Docker 部署执行）
└── deploy-web/      # Vue3 + TS + Element Plus 管理台
```

各子项目 README 见对应目录。

## 快速开始

### 1) 启动中心服务（deploy-server）

```bash
cd deploy-server
python -m venv .venv && source .venv/bin/activate   # 推荐 Python 3.10+
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000
```

API 文档： http://127.0.0.1:8000/docs

### 2) 启动客户端（deploy-client）

```bash
cd deploy-client
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 注册 + 心跳 + 开放探活/部署 HTTP 服务（Ctrl+C 停止）
python -m cli.main run --name node-1 --url http://127.0.0.1:8000 --probe-port 9090
```

注册时可用环境变量上报**本机部署环境初值**（之后以中心「本机配置」页为准）：

| 环境变量 | 说明 |
|---|---|
| `DCC_DATA_ROOT` | 数据卷根目录（持久化挂载） |
| `DCC_DEPLOY_ROOT` | 部署/构建根目录（项目部署目录 = 它 + 子路径） |
| `DCC_REGISTRY_MIRROR` | 镜像加速源前缀，如 `docker.m.daocloud.io/` |
| `DCC_DOCKER_NETWORK` | 默认 docker 网络 |
| `DCC_MAX_CPU` / `DCC_MAX_MEMORY` | 单容器资源上限 |

### 3) 启动 Web 管理台（deploy-web）

```bash
cd deploy-web
npm install
npm run dev        # http://127.0.0.1:5173 （/api 已代理到 8000）
```

### 4) 验证负载均衡

```bash
# 在双客户端在线时，用 CLI 演示派发 9 个任务：
cd deploy-client && python -m cli.main demo --clients 2 --tasks 9
# 或在 Web「任务管理」页点「演示派单」，观察任务被轮询分派到不同 client
```

## 数据库与缓存

- **数据库**：`deploy-server/data/center.db`（SQLite 单文件），表：
  `clients` / `client_configs` / `projects` / `tasks`。
- **缓存**：`deploy-server/app/core/cache.py` 提供零依赖的全局缓存：
  - `ThreadLocalCache`：线程隔离（同步端点）；
  - `ContextVarCache`：asyncio 任务隔离（异步端点）；
  - 全局单例 `cache_manager` 按名称注册获取，均支持 TTL 与 LRU。
  备选方案：`cachetools`（纯 Python、线程安全、零服务依赖）。

## 说明与后续扩展点

- 认证目前预留 token 字段，未强制校验；可扩展 FastAPI 依赖做 Bearer 校验。
- SQLite 建表为启动时自动 create_all；规模化后可引入 Alembic 迁移 + 更换 PostgreSQL。
- server 层无状态：session 均随请求创建销毁，适合多实例水平扩展。
- client 与 center 当前为 REST + 轮询；大批量实时场景可扩展为 WebSocket 长连接。
- 部署暂按 Linux 主机实现（`platform` 字段已预留 `windows/darwin`）；Windows 主机
  建议先走 Docker Desktop/WSL2（Linux 容器），原生 Windows 容器暂不支持。