# contra

**Repository Path**: parselife/contra

## Basic Information

- **Project Name**: contra
- **Description**: 一个简单的运维管理平台，管理主机、k8s集群、容器等
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Contra

运维管理平台 — 集中管理 Linux 主机、K8s 集群与 Docker 容器，覆盖构建交付、部署、监控告警的一体化运维闭环。

## 功能特性

- **主机管理**：SSH 隧道集中管理，实时指标采集（CPU/内存/磁盘/负载），进程与端口巡检
- **容器管理**：容器列表、详情、日志、终端、统计信息
- **Compose 管理**：Compose 项目部署、启停、日志查看、状态监控
- **镜像管理**：镜像列表查看
- **Java 应用发现**：自动识别 Java 进程并解析 JVM 参数（Xmx/Xms/GC/主类/版本），支持热日志查看
- **告警模块**：
  - 主机指标越界告警（CPU/内存/磁盘/负载），关注容器状态恶化告警，新容器上线告警，主机失联告警
  - 告警规则与通道 UI 可配置，支持企业微信 Bot 等多通道并行分发
  - 告警静默期防风暴、恢复通知、实时 SSE 推送（前端铃铛角标 + 弹窗）
  - 监控轮询间隔可配置，告警历史记录查询
- **用户与权限**：多用户支持，管理员/操作员/只读三种角色
- **审计日志**：关键操作记录与查询

## 技术栈

- **前端**：React 18 + Ant Design 5 + Vite 5 + TanStack Query
- **后端**：Hono + tsx（Node.js 22）+ better-sqlite3 + dockerode + ssh2
- **共享层**：TypeScript + Zod（类型契约前后端共享）
- **构建**：npm workspaces monorepo

## 项目结构

```
contra/
├── apps/
│   ├── server/          # Hono 后端（API + 静态文件服务 + 告警监控引擎）
│   └── web/             # Vite SPA 前端
├── docker/              # Docker 部署文件
│   ├── Dockerfile       # 多阶段构建（builder + runtime）
│   ├── docker-compose.yml
│   ├── .env.example
│   └── build.sh         # 构建推送脚本
├── docs/                # 设计方案文档
│   └── alerts.md        # 告警模块设计方案
└── .dockerignore
```

## 开发模式

### 环境要求

- Node.js >= 22
- npm >= 10

### 启动开发服务

```bash
npm install
npm run dev
```

前端运行在 `http://localhost:5173`，后端在 `http://localhost:8787`。Vite dev server 会自动将 `/api` 请求代理到后端。

### 类型检查与构建

```bash
npm run typecheck    # 全包类型检查
npm run build        # 构建 shared + web
```

---

## Docker 部署

采用单容器方案：一个容器同时提供后端 API 和前端静态文件服务。

### 架构说明

- **多阶段 Dockerfile**：Stage 1 安装依赖并构建 shared + web；Stage 2 只拷贝产物和生产依赖，tsx 直跑
- **前端静态文件**：`web/dist` 被拷贝到容器内 `/app/public/`，由 Hono `serveStatic` 同域服务，无 CORS 问题
- **数据持久化**：SQLite 文件通过 bind mount 挂载到宿主机 `CONTRA_DATA_DIR`（默认 `./data`），数据直接可见、便于备份
- **网络连通性**：Contra 通过 SSH 出站连接远端主机，默认 bridge 模式即可；若远端主机在 VPN/内网，改用 host 模式

### 前置条件

- Docker（含 buildx 插件）
- Docker Compose v2
- 阿里云 ACR 账号（仅推送镜像时需要）

### 1. 配置环境变量

```bash
cd docker
cp .env.example .env
```

编辑 `.env`，**必须设置**以下项：

```ini
# 安全密钥（64 位 hex），用于凭据加密和 JWT 签名
# 生成方式：openssl rand -hex 32
CONTRA_SECRET_KEY=<你的密钥>
```

其他可选项按需调整：

- `CONTRA_PORT` — 对外端口，默认 8787
- `CONTRA_DATA_DIR` — 数据持久化目录（宿主机），默认 `./data`
- `CONTRA_VERSION` — 镜像版本/标签，默认 `latest`
- `CORS_ORIGINS` — 跨域允许地址（逗号分隔），同容器部署留空即可
- `ALIYUN_REGISTRY` / `ALIYUN_NAMESPACE` — 阿里云 ACR 地址和命名空间
- `BUILD_PLATFORM` — 目标架构，默认 linux/amd64

### 2. 构建镜像

在 `docker/` 目录下执行：

```bash
# 构建镜像（本地）
./build.sh

# 不使用缓存全量构建
./build.sh --no-cache

# 构建并直接启动
./build.sh --up

# 查看帮助
./build.sh --help
```

`build.sh` 会自动从 `package.json` 读取版本号作为镜像 tag。

### 3. 推送镜像到阿里云 ACR

首次使用需先登录：

```bash
docker login registry.cn-hangzhou.aliyuncs.com -u <阿里云账号> -p <访问凭证>
```

推送：

```bash
# 推送当前版本
./build.sh --push

# 推送并附加 :latest 标签
./build.sh --latest

# 等价于 --push --latest
./build.sh --acr
```

### 4. 服务器部署

将 `docker/` 目录下的 `docker-compose.yml` 和 `.env` 传到服务器，然后：

```bash
# 拉取最新镜像并启动（在 docker/ 目录下执行）
docker compose pull
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f

# 停止（保留数据）
docker compose down

# 停止并清空数据（慎用）
docker compose down -v
```

> **说明**：本项目根目录提供了 `compose.yaml` 包装文件，因此在**项目根目录**也可以直接运行
> `docker compose pull / up -d / down`，无需进入 `docker/` 目录。
> 首次使用请确保 `docker/.env` 存在（不存在时复制 `docker/.env.example` 并按提示填写
> `CONTRA_SECRET_KEY` 等必填项），否则会报 `no configuration file provided: not found`
> 或 `CONTRA_SECRET_KEY` 未设置的错误。

### 5. 升级更新

```bash
# 拉取新版本镜像
docker compose pull

# 重启容器（数据卷保留）
docker compose up -d
```

### 网络模式选择

**默认 bridge 模式**（适用于远端主机是公网 IP 或同网段）：

容器通过 NAT 出站 SSH 连接远端主机，无需额外配置。

**host 模式**（适用于远端主机在 VPN/内网）：

编辑 `docker-compose.yml`，注释掉 `ports` 映射，取消注释 `network_mode: host`：

```yaml
services:
  contra:
    # ports:
    #   - "${CONTRA_PORT:-8787}:8787"
    network_mode: host
```

host 模式下容器直接使用宿主机网络栈，可访问宿主机能访问的所有网络（VPN、内网网段等）。

### 手动构建（不使用 build.sh）

```bash
# 在仓库根目录执行
docker build -f docker/Dockerfile -t contra:0.7.0 .

# 运行（构建需直连宿主机 Docker，故挂载 docker.sock 与构建工作区，两者须与宿主机同路径）
mkdir -p /var/lib/contra
docker run -d --name contra -p 8787:8787 \
  -e CONTRA_SECRET_KEY=$(openssl rand -hex 32) \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v contra-data:/app/data \
  -v /var/lib/contra:/var/lib/contra \
  contra:0.7.0
```

### 跨架构构建

在 Apple Silicon (arm64) 上为 amd64 服务器构建镜像：

```bash
./build.sh --platform linux/amd64
```

`build.sh` 会自动检测架构差异并注册 qemu 模拟器。如自动注册失败，手动执行：

```bash
docker run --privileged --rm tonistiigi/binfmt --install all
```

---

## 环境变量说明

| 变量                | 必填 | 说明                                 | 默认值              |
| ------------------- | ---- | ------------------------------------ | ------------------- |
| `CONTRA_SECRET_KEY` | 是   | 凭据加密 + JWT 签名密钥（64 位 hex） | 无（开发回退密钥）  |
| `PORT`              | 否   | 服务监听端口                         | 8787                |
| `CONTRA_DB_PATH`    | 否   | SQLite 文件路径                      | /app/data/contra.db |
| `CONTRA_DATA_DIR`   | 否   | 数据持久化目录（宿主机，bind mount） | ./data              |
| `CONTRA_VERSION`    | 否   | 镜像版本/标签                        | latest              |
| `CORS_ORIGINS`      | 否   | CORS 允许地址（逗号分隔）            | 空（同域）          |
| `TZ`                | 否   | 时区                                 | Asia/Shanghai       |