# zcd

**Repository Path**: bolt/zcd

## Basic Information

- **Project Name**: zcd
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zero-Config Deploy

为非技术用户打造的零配置一键部署系统。只需一个 CLI 命令，即可将本地项目自动检测、构建并部署到服务器，并通过统一网关访问。

## 快速开始

### 安装依赖

```bash
pnpm install
```

### 启动服务端

```bash
pnpm dev:server
```

服务端默认运行在 `http://localhost:3000`。

### 使用 CLI 部署项目

```bash
pnpm dev:cli -- <项目路径> --server http://localhost:3000
```

示例：

```bash
pnpm dev:cli -- ./my-vite-app --server http://localhost:3000
```

CLI 会自动打包项目目录、上传、订阅部署日志并轮询部署进度，最终返回可访问的 URL。

## 项目结构

```
.
├── docs/                  # 文档驱动开发产物
│   ├── requirements/      # 需求文档
│   ├── design/            # 设计文档
│   └── adr/               # 架构决策记录
├── packages/
│   ├── cli/               # 客户端 CLI
│   └── server/            # 服务端 Deploy Agent、管理后台与网关
├── package.json
├── pnpm-workspace.yaml
└── README.md
```

## 技术栈支持

| 语言/框架 | 检测依据 | 部署方式 |
|-----------|----------|----------|
| Node.js (Next.js, React, Vue, Vite) | `package.json` | Docker / containerd / K8s |
| Python (Flask, FastAPI, Django) | `requirements.txt` / `pyproject.toml` / `Pipfile` | Docker / containerd / K8s |
| Go | `go.mod` | Docker / containerd / K8s |
| Rust | `Cargo.toml` | Docker / containerd / K8s |
| Java | Maven / Gradle 项目文件 | Docker / containerd / K8s |

## 主要能力

- CLI 部署：项目打包、上传、环境变量确认、实时日志和任务轮询。
- 自动检测：根据项目文件检测 Node.js、Python、Go、Rust、Java 技术栈。
- 多运行时：支持本地 Docker/containerd 部署，也支持 K8s Deployment + Service 部署。
- 管理后台：内置 `/dashboard` 页面，管理部署任务、容器、Pod、应用和用户。
- 应用市场：内置 `/market` 页面，展示已注册应用。
- 统一网关：部署成功后注册应用，通过 `/app/{slug}` 访问。
- 持久化：用户、应用、权限、会话和部署任务存储在 SQLite。

## 环境变量

- `PORT`：服务端监听端口（默认 3000）
- `ADMIN_BASE_URL`：后台管理对外访问基地址，用于统一登录入口、认证回调与后台链接生成
- `ZCD_SERVER`：CLI 默认连接的服务端地址
- `DEPLOY_MODE=k8s`：启用 K8s 部署模式
- `K8S_NAMESPACE`：K8s 部署 namespace
- `K8S_REGISTRY_URL`：K8s 模式镜像仓库地址
- `K8S_REGISTRY_NS`：K8s 模式镜像仓库命名空间
- `K8S_KUBECONFIG`：kubeconfig 路径
- `K8S_CONTEXT`：kubectl context
- `K8S_IMAGE_PULL_SECRET`：Pod 拉取私有镜像使用的 Secret
- `K8S_SERVICE_TYPE`：K8s Service 类型，支持 `ClusterIP` 和 `NodePort`

## 开发命令

| 命令 | 说明 |
|------|------|
| `pnpm dev:server` | 启动服务端（Bun + Elysia） |
| `pnpm dev` | 启动服务端 |
| `pnpm dev:cli -- <项目路径> --server http://localhost:3000` | 运行 CLI 部署项目 |
| `pnpm build` | 构建所有包 |

## 设计原则

- **客户端极简**：用户只需安装轻量 CLI，无需本地 Docker、containerd、kubectl 或语言运行时。
- **服务端编排**：检测、构建、部署、应用注册和网关访问均由服务端完成。
- **隔离执行**：用户项目不直接在宿主机全局环境运行，而是通过容器或 K8s 资源隔离。
- **开放封闭**：新增语言/框架支持时，只需在服务端添加 Detector 和镜像构建模板，无需修改 CLI 核心逻辑。