Skip to content
BranchesTags

Repository files navigation

Cloudaril

多云资源聚合与运维控制台。

Release workflow GHCR image License

Cloudaril 将云服务器、域名、DNS 和 AI 模型统一到一个控制面，并通过 REST API 与 MCP Server 对外提供自动化能力。

直接运行发布镜像

一分钟启动（SQLite）

这个方式只需要 Docker，不需要额外启动 PostgreSQL 或 Redis，适合快速体验和个人使用：

export CLOUDARIL_MASTER_KEY="$(openssl rand -base64 32)"

docker pull ghcr.io/deershark/cloudaril:latest
docker run -d \
  --name cloudaril \
  --restart unless-stopped \
  -p 8080:8080 \
  -e CLOUDARIL_DB_DRIVER=sqlite \
  -e CLOUDARIL_ADMIN_USERNAME=admin \
  -e CLOUDARIL_ADMIN_PASSWORD=change-me-now \
  -e CLOUDARIL_MASTER_KEY="$CLOUDARIL_MASTER_KEY" \
  -v cloudaril-data:/data \
  ghcr.io/deershark/cloudaril:latest

打开 http://localhost:8080，使用 admin / change-me-now 登录控制台。首次启动会将管理员账号和密码初始化到数据库；后续重启不会用环境变量覆盖数据库中的凭据。

生产环境请将 CLOUDARIL_ADMIN_PASSWORD 改成强密码，并固定保存 CLOUDARIL_MASTER_KEY。不要在容器重建后更换主密钥，否则历史云凭据无法解密。

使用 PostgreSQL + Redis

从仓库运行完整依赖栈：

git clone https://github.com/deershark/cloudaril.git
cd cloudaril

export CLOUDARIL_MASTER_KEY="$(openssl rand -base64 32)"
export CLOUDARIL_ADMIN_USERNAME='admin'
export CLOUDARIL_ADMIN_PASSWORD='change-me-now'
docker compose pull
docker compose up -d

仓库中的 docker-compose.yml 默认使用 ghcr.io/deershark/cloudaril:latest，并启动 PostgreSQL、Redis 和 Cloudaril 服务，数据保存在 Docker volumes 中。默认访问地址仍为 http://localhost:8080。

如果要从当前源码构建而不是使用 GHCR 镜像：

docker build -t cloudaril:local .
CLOUDARIL_IMAGE=cloudaril:local docker compose up -d

查看日志或停止服务：

docker compose logs -f cloudaril
docker compose stop

发布镜像地址：

ghcr.io/deershark/cloudaril:latest
ghcr.io/deershark/cloudaril:<version>

升级

单容器部署

docker pull ghcr.io/deershark/cloudaril:latest
docker stop cloudaril
docker rm cloudaril

然后使用上面的 docker run 命令重新创建容器。只要保留 cloudaril-data volume，SQLite 数据不会丢失。

Compose 部署

docker compose pull
docker compose up -d

默认 Compose 配置使用 GHCR 发布镜像；从源码部署时设置 CLOUDARIL_IMAGE=cloudaril:local 即可切换到本地构建的镜像。

功能

  • 云服务器：跨账号实例聚合、详情、启动、停止、重启和 CPU / 内存 / 带宽监控。
  • 域名与 DNS：域名列表、DNS 记录增删改查、Cloudflare 代理状态、DNSPod 启停状态。
  • RDAP：查询注册信息和到期时间，临近到期时在控制台提示。
  • AI 模型：聚合各云账号可用模型和模型 Key。
  • REST API：JWT 与 API Key 双认证，适合脚本和 CI。
  • 控制台安全：管理员账号和 bcrypt 密码哈希存储在数据库，支持 TOTP 2FA；未启用时控制台会持续提醒。
  • MCP Server：让 Claude、Cursor 等 AI 客户端直接操作云资源。
  • Provider：当前支持腾讯云、UCloud、Cloudflare，并保留扩展其他云厂商的适配器接口。

首次配置云账号

  1. 打开控制台并登录。
  2. 进入「云账号」页面。
  3. 选择 Provider，填写云厂商凭据。
  4. 保存前执行凭据连通性校验。
  5. 返回总览、实例、域名或模型页面查看资源。

不想配置真实凭据时，可以选择 演示（fake） Provider 体验内置数据。

配置项

环境变量 说明 默认值
CLOUDARIL_ADDR 服务监听地址 :8080
CLOUDARIL_DATA_DIR 数据目录 ./data
CLOUDARIL_WEB_DIR 前端构建产物目录 ./web/dist
CLOUDARIL_ADMIN_USERNAME 控制台管理员账号（仅首次初始化使用） admin
CLOUDARIL_ADMIN_PASSWORD 控制台管理密码（仅首次初始化使用，至少 8 位） admin123
CLOUDARIL_MASTER_KEY Base64 编码的 32 字节凭据加密主密钥 开发密钥
CLOUDARIL_DB_DRIVER postgres 或 sqlite postgres
CLOUDARIL_PG_DSN PostgreSQL 连接串 postgres://cloudaril:cloudaril@localhost:5432/cloudaril?sslmode=disable
CLOUDARIL_SQLITE_PATH SQLite 文件路径 <DATA_DIR>/cloudaril.db
CLOUDARIL_REDIS_ADDR Redis 地址 localhost:6379
CLOUDARIL_REDIS_PASSWORD Redis 密码 空
CLOUDARIL_REDIS_DB Redis 逻辑库编号 0
CLOUDARIL_CACHE 是否启用资源缓存 开启
CLOUDARIL_CACHE_INTERVAL 缓存刷新间隔 5m
CLOUDARIL_MODEL_KEY_EDIT 是否允许在线编辑模型 Key 可访问模型 关闭

未设置 CLOUDARIL_MASTER_KEY 时，开发环境会使用内置密钥并打印告警；生产环境必须显式设置。

管理员首次启动时由 CLOUDARIL_ADMIN_USERNAME 和 CLOUDARIL_ADMIN_PASSWORD 创建数据库用户，密码只以 bcrypt 哈希保存。登录控制台后进入「系统设置 → 安全设置」，按提示扫描本地生成的 TOTP 二维码并确认 6 位验证码即可启用 2FA；页面同时保留备用密钥和 URI。启用后登录必须同时提供密码和动态验证码；如果没有启用，控制台会显示安全提醒。账号或密码也可以在该页面修改，已启用 2FA 时修改操作还需要当前动态码。

REST API

认证方式：

  • 登录后使用 Authorization: Bearer <JWT>。
  • 自动化脚本使用 X-API-Key: oc_...。

常用接口：

方法 路径 说明
POST /api/v1/auth/login 登录获取 JWT
GET /api/v1/settings/public 获取登录页所需的公开站点配置
GET /api/v1/settings 获取系统设置（仅 JWT）
PUT /api/v1/settings 更新系统设置（仅 JWT，Logo/Favicon 仅支持 HTTPS）
GET /api/v1/auth/security 查看管理员安全状态（仅 JWT）
PUT /api/v1/auth/credentials 修改管理员账号/密码（仅 JWT，需当前密码；已启用 2FA 时还需动态码）
POST /api/v1/auth/2fa/setup 生成 2FA 配置（仅 JWT）
POST /api/v1/auth/2fa/enable 使用 6 位验证码启用 2FA（仅 JWT）
DELETE /api/v1/auth/2fa 使用 6 位验证码关闭 2FA（仅 JWT）
GET /api/v1/providers 查看已注册 Provider
GET / POST /api/v1/accounts 查询 / 创建云账号
GET /api/v1/instances 聚合实例列表
POST /api/v1/instances/action 实例启动、停止、重启
GET /api/v1/domains 查询域名列表
GET / POST /api/v1/domains/{domain}/records 查询 / 创建 DNS 记录
PUT / DELETE /api/v1/domains/{domain}/records/{recordId} 修改 / 删除 DNS 记录
GET /api/v1/models 查询模型目录
GET /api/v1/modelkeys 查询模型 Key
GET / POST / DELETE /api/v1/apikeys[/{id}] 管理 API Key

示例：

cloudaril-server -create-apikey my-ci
curl -H "X-API-Key: oc_xxxxxxxx" \
  http://localhost:8080/api/v1/instances

MCP Server

构建 MCP Server：

cd backend
go build -o cloudaril-mcp ./cmd/mcp

Claude Desktop / Cursor 配置：

{
  "mcpServers": {
    "cloudaril": {
      "command": "/path/to/cloudaril-mcp",
      "env": {
        "CLOUDARIL_DATA_DIR": "/path/to/data",
        "CLOUDARIL_MASTER_KEY": "与 REST Server 一致的主密钥"
      }
    }
  }
}

MCP 工具覆盖账号、实例、实例操作、域名、DNS 记录、模型和模型 Key 管理。关机、删除 DNS 记录等危险操作会带有 destructiveHint 标记。

本地开发

运行环境

  • Docker Engine 与 Docker Compose
  • Go 1.25+
  • Node.js 22+

先启动 PostgreSQL 与 Redis：

docker compose -f docker-compose.dev.yml up -d

启动后端：

cd backend
CLOUDARIL_PG_DSN='postgres://cloudaril:cloudaril@localhost:5432/cloudaril?sslmode=disable' \
CLOUDARIL_REDIS_ADDR=localhost:6379 \
go run ./cmd/server

另开终端启动前端：

cd web
npm install
npm run dev

前端地址为 http://localhost:5173，Vite 会将 API 请求代理到后端 :8080。本地也可以使用 SQLite：

cd backend
CLOUDARIL_DB_DRIVER=sqlite go run ./cmd/server

验证代码：

cd backend && go test ./...
cd ../web && npm run typecheck && npm run build

项目结构

cloudaril/
├── Dockerfile
├── docker-compose.yml
├── docker-compose.dev.yml
├── backend/
│   ├── cmd/server/          # REST API 与 SPA 托管
│   ├── cmd/mcp/             # MCP Server
│   └── internal/
│       ├── provider/        # 云厂商适配器
│       ├── service/         # 跨账号聚合业务
│       ├── api/             # REST 路由与中间件
│       ├── mcp/             # MCP 协议实现
│       ├── store/           # PostgreSQL / SQLite 持久化
│       └── config/          # 环境变量配置
└── web/                     # React + Vite 控制台

安全建议

  • 生产环境使用随机且固定的 CLOUDARIL_MASTER_KEY，不要提交到 Git。
  • 设置强 CLOUDARIL_ADMIN_PASSWORD，并将服务放在 TLS 反向代理之后。
  • 限制 PostgreSQL、Redis 端口只监听内网或回环地址。
  • API Key 只在创建时展示一次，请使用 Secret Manager 或 CI Secret 保存。
  • 备份数据库和数据目录，并定期轮换云厂商凭据。

贡献与 License

欢迎提交 Issue、PR 和新的 Provider 适配器。提交 PR 前请运行后端测试以及前端 typecheck / build，并确保不提交密钥、账号凭据或本地数据目录。更多协作约定见 CONTRIBUTING.md。

本项目使用 MIT License。

About

自托管的多云资源控制台：统一管理云服务器、域名、DNS 与 AI 模型，并通过 REST API 和 MCP Server 接入自动化与 AI 客户端。A self-hosted multi-cloud control plane for managing servers, domains, DNS, and AI models through one dashboard, REST API, and MCP Server.

Topics

aiai-toolscloudcloudflareconsoletencent-cloud

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages