Incudal

基于 Incus 的 LXC / KVM NAT VPS 销售、交付与管理面板。

项目简介

Incudal 基于 Incus 的 NAT VPS 销售与管理面板。 项目支持 LXC / KVM 实例、套餐与镜像管理、账务计费、节点托管、用户后台、管理员后台以及宿主机 Agent。

演示站：https://demo.incudal.com
仅供学习与参考，本项目存在诸多不完善之处。有任何问题建议 Fork 后使用 AI 解决。

主要功能

• 实例交付：基于 Incus 创建和管理 LXC / KVM 实例，支持 NAT 网络、系统镜像、套餐资源和节点绑定。
• 平台运营：提供用户端与管理员后台，覆盖用户、套餐、镜像、节点、工单、公告、日志和系统配置等管理流程。
• 计费与权益：支持余额、充值、消费记录、托管收益、支付渠道、积分、VIP 等级和会员福利。
• 节点与扩展：通过宿主机 Agent 上报资源与状态，并支持托管节点、反代建站、邮箱服务等扩展能力。

目录结构

client/                 Vue 3 + Vite 前端
server/                 Fastify + Prisma 后端
agent/                  Go 宿主机 Agent
server/prisma/          数据库 schema 与 migrations
server/templates/       安装脚本、邮件等模板
.github/workflows/      CI、Docker、Agent Release 工作流
scripts/                本地开发和检查脚本

搭建教程

当前无论使用哪种部署方式，都需要在 server/certs 目录下生成或放置证书与密钥，并确保 Docker 容器具有读取权限。

方式一：Docker Compose 开发环境

适合本地试跑和开发预览。该方式会自动启动 Node、PostgreSQL 和 Redis，并自动安装依赖、执行数据库迁移。

git clone https://github.com/qwer-xyz/incudal.git
cd incudal
docker compose -f docker-compose.dev.yml up

启动后访问：

前端：http://127.0.0.1:43173
后端：http://127.0.0.1:8888

停止服务：

docker compose -f docker-compose.dev.yml down

如需同时删除本地开发数据库卷：

docker compose -f docker-compose.dev.yml down -v

方式二：生产镜像部署

生产环境建议准备独立 PostgreSQL 和 Redis，然后构建并运行镜像。

docker build -t incudal:local .
docker run -d --name incudal \
  -p 3000:3000 \
  --env-file .env \
  incudal:local

生产环境至少需要配置：

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://user:password@postgres:5432/incudal
REDIS_URL=redis://redis:6379
JWT_SECRET=please-change-to-a-long-random-secret
FRONTEND_URL=https://your-domain.example

容器启动时会执行 prisma migrate deploy，然后启动后端服务。生产部署前请确保数据库可连接、JWT_SECRET 足够随机、反向代理和 HTTPS 已配置好。

Agent 正式二进制不存放在面板仓库内，面板运行时会从 GitHub Release 查询和代理下载。如部署在私有仓库或 fork，可按需配置：

INCUDAL_AGENT_RELEASE_REPOSITORY=qwer-xyz/incudal
INCUDAL_AGENT_RELEASE_TOKEN=github_pat_xxx

开发教程

本地依赖

• Node.js 20 或更高版本
• pnpm 9.14.2
• PostgreSQL
• Redis
• Go 1.22 或更高版本，仅开发 Agent 时需要

启用 pnpm：

corepack enable
corepack prepare pnpm@9.14.2 --activate
pnpm install

配置本地环境变量后执行数据库迁移：

pnpm --filter server exec prisma migrate deploy

启动前后端开发服务：

pnpm dev

默认开发端口：

client: http://127.0.0.1:5173
server: http://127.0.0.1:8888

常用命令

pnpm --filter client type-check
pnpm --filter server type-check
pnpm build
pnpm lint

本地检查：

# Windows
.\scripts\local-ci.ps1
# macOS
.\scripts\local-ci-macos.sh

数据库开发

Prisma schema 位于 server/prisma/schema.prisma，迁移文件位于 server/prisma/migrations/。修改数据库结构后，应生成迁移并确认前后端类型检查通过。

常用命令：

pnpm --filter server exec prisma generate
pnpm --filter server exec prisma migrate dev
pnpm --filter server exec prisma migrate deploy

Agent 开发与发布

Agent 位于 agent/，版本号统一由 agent/VERSION 控制。

本地测试：

cd agent
go test ./...
go run ./cmd/incudal-agent -config ./config.example.yaml -once

本地构建双架构产物：

bash agent/scripts/build-release.sh

agent/dist 只是本地临时构建目录，不提交到 Git。正式发布由 GitHub Actions Agent Build & Release 完成：当 agent/VERSION 变动并推送后，会发布 GitHub Release，并生成：

incudal-agent-x86_64-v0.0.1
incudal-agent-aarch64-v0.0.1

开发约定

• 前端新增文案需要同步维护 client/src/locales/ 下的多语言键。
• 后端新增管理接口应使用登录鉴权和管理员鉴权，并补充必要的字段校验和速率限制。
• 数据库变更需要提交 Prisma migration，不直接修改生产库结构。
• 不提交构建产物、临时文件、密钥、数据库 dump 或本地 .env。