Community-VyProjects/VyManager
GitHub: Community-VyProjects/VyManager
VyManager 是一个基于现代 Web 界面的集中式 SDN 控制器，用于统一配置、部署和监控多站点的 VyOS 路由器，解决了大规模 VyOS 环境下逐台管理的低效问题。
Stars: 254 | Forks: 27
# VyManager
## 企业级 VyOS 路由器管理系统
通过现代 Web 界面集中管理、部署和监控多站点 VyOS 路由器的平台
## 公测社区版
开放测试版本。我们灵活支持所有活跃的 VyOS 版本，包括滚动发布版。
### [跳转到快速开始](#quick-start)
**[加入我们的 Discord 社区以获取官方更新](https://discord.gg/k9SSkK7wPQ)**
**[在线演示](https://vyprojects.org/)**
### 截图
VyManager 用户界面支持浅色和深色主题。
## 快速开始
### 前置条件
- 主机上已安装 **Docker & Docker Compose**
- 已启用 REST API 和 GraphQL 的 **VyOS 路由器**（参见 [步骤 1](#step-1-enable-the-vyos-rest-api)）
## 部署指南
### 步骤 1：启用 VyOS REST API
在部署 VyManager 之前，请在您的 VyOS 路由器上启用 REST API。
通过 SSH 连接到您的 VyOS 路由器并运行：
```
# 进入配置模式
configure
# 创建 API 密钥（将 YOUR_SECURE_API_KEY 替换为一个强壮的随机密钥）
set service https api keys id vymanager key YOUR_SECURE_API_KEY
# 启用 REST 功能（仅限 VyOS 1.5+）
set service https api rest
# 启用 GraphQL（dashboard streaming 需要此功能）
set service https api graphql
# 将 GraphQL 身份验证设置为使用上面定义的 API 密钥
set service https api graphql authentication type key
# 保存并应用
commit
save
exit
```
### 步骤 2：创建项目目录
为 VyManager 创建一个新目录并进入该目录：
```
mkdir vymanager
cd vymanager
```
您将在此目录中创建两个文件：`docker-compose.yml` 和 `.env`。
### 步骤 3：创建 docker-compose.yml
创建一个名为 `docker-compose.yml` 的文件，内容如下：
```
services:
postgres:
image: postgres:16-alpine
container_name: vymanager-postgres
environment:
POSTGRES_USER: vymanager
POSTGRES_PASSWORD: CHANGE_ME_POSTGRES_PASSWORD
POSTGRES_DB: vymanager
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
networks:
- vymanager-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U vymanager -d vymanager"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
backend:
image: ghcr.io/community-vyprojects/vymanager-backend:beta
container_name: vymanager-backend
ports:
- "8000:8000"
volumes:
- ./certs:/usr/local/share/ca-certificates/custom:ro
env_file:
- .env
restart: unless-stopped
networks:
- vymanager-network
depends_on:
postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/docs"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
frontend:
image: ghcr.io/community-vyprojects/vymanager-frontend:beta
container_name: vymanager-frontend
ports:
- "3000:3000"
env_file:
- .env
depends_on:
backend:
condition: service_healthy
postgres:
condition: service_healthy
restart: unless-stopped
networks:
- vymanager-network
networks:
vymanager-network:
driver: bridge
volumes:
postgres_data:
driver: local
```
### 步骤 4：创建 .env 文件
在同一目录中创建一个名为 `.env` 的文件。后端和前端容器都将从此单一文件中读取配置。
在启动之前，您**必须**更改以下值：
1. **`POSTGRES_PASSWORD`** — 在 `docker-compose.yml` 和下面的 `DATABASE_URL` 中**同时**修改；它们必须保持一致。生成方式：`openssl rand -hex 32`
2. **`BETTER_AUTH_SECRET`** — 用于签名和验证会话 token；在文件中会出现**两次**（每个服务一次），且两处的值必须**相同**。生成方式：`openssl rand -base64 32`
3. **`SSH_ENCRYPTION_KEY`** — 用于加密静态存储的 SSH 私钥。生成方式：`openssl rand -hex 32`
4. **`BETTER_AUTH_URL` / `NEXT_PUBLIC_APP_URL`** — 将 `` 替换为用户在浏览器中打开的 IP 或主机名。
5. **`TRUSTED_ORIGINS`** — 用户访问 VyManager 的所有 URL 的逗号分隔列表。
```
# ── 后端 ──────────────────────────────────────────────
# CHANGE_ME_POSTGRES_PASSWORD 必须与 docker-compose.yml 中的 POSTGRES_PASSWORD 匹配
DATABASE_URL=postgresql://vymanager:CHANGE_ME_POSTGRES_PASSWORD@postgres:5432/vymanager
FRONTEND_URL=http://frontend:3000
# 更改此项 — 使用较长的随机字符串（例如 openssl rand -base64 32）
# 必须与下面的 BETTER_AUTH_SECRET 值匹配 — 两个服务都使用此文件
BETTER_AUTH_SECRET=Change-This-To-Something-Secret
# 更改此项 — 使用较长的随机十六进制字符串（例如 openssl rand -hex 32）
SSH_ENCRYPTION_KEY=Change-This-To-A-Hex-String
# ── 前端 ─────────────────────────────────────────────
NODE_ENV=production
VYMANAGER_ENV=production
# 必须与上面的 BETTER_AUTH_SECRET 值相同
BETTER_AUTH_SECRET=Change-This-To-Something-Secret
# 更改此项 — 设置为用户在浏览器中访问 VyManager 的 URL
BETTER_AUTH_URL=http://:3000
NEXT_PUBLIC_APP_URL=http://:3000
# 内部 Docker 网络 URL — 除非重命名 backend service，否则请勿更改
BACKEND_URL=http://backend:8000
# 更改此项 — 以逗号分隔的用户将从中访问 VyManager 的每一个 URL 列表
# 示例：http://192.168.1.50:3000,http://vymanager.lan:3000
TRUSTED_ORIGINS=http://:3000,http://localhost:3000
```
### 步骤 5：启动 VyManager
在 `vymanager` 目录中运行：
```
docker compose up -d
```
Docker 将拉取镜像，启动 PostgreSQL，等待其状态变为 healthy 后，启动后端和前端。首次运行时可能需要一分钟。
检查三个容器是否都在运行：
```
docker compose ps
```
您应该会看到 `vymanager-postgres`、`vymanager-backend` 和 `vymanager-frontend` 都处于 **healthy** / **running** 状态。
### 步骤 6：完成设置向导
1. **打开浏览器** 并访问 `http://:3000`
2. **新手引导向导** 将在首次访问时自动启动：
- **步骤 1**：创建您的管理员账户
- **步骤 2**：创建您的第一个站点（例如：“总部”）
- **步骤 3**：添加您的第一个 VyOS 实例
- Name（名称）：为其起一个友好的名称
- Host（主机）：您的 VyOS 路由器 IP 地址
- Port（端口）：443（默认）
- API Key（API 密钥）：您在步骤 1 中创建的密钥
- Version（版本）：选择您的 VyOS 版本（1.4 或 1.5）
3. **开始管理！** 您将自动登录并被重定向到控制面板。
## 管理部署
### 常用 Docker 命令
```
# 查看日志（所有服务）
docker compose logs -f
# 查看单个服务的日志
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres
# 停止所有服务
docker compose down
# 重启所有服务
docker compose restart
# 重启单个服务
docker compose restart backend
# 拉取最新镜像并重建容器
docker compose pull
docker compose up -d
# 移除所有内容，包括数据库卷
docker compose down -v
```
### 更新 VyManager
当发布新版本时，通过拉取最新镜像进行更新：
```
cd vymanager
docker compose pull
docker compose up -d
```
您的数据库和配置将保留在 `postgres_data` 卷中。
## 架构概述
### 多实例管理
VyManager 采用**多实例架构**，允许您通过单一界面管理多台 VyOS 路由器：
- **站点 (Sites)**：VyOS 实例的逻辑分组（例如：“数据中心 01”，“纽约分部”）
- **实例 (Instances)**：站点内的独立 VyOS 路由器
- **基于角色的访问控制**：每个站点支持 OWNER、ADMIN 和 VIEWER 角色
- **活动会话**：一次连接到一个实例进行配置
### 数据库驱动配置
VyManager 将所有实例配置存储在 PostgreSQL 数据库中：
```
PostgreSQL Database
├── users # User accounts
├── sites # Site groupings
├── instances # VyOS router instances
├── permissions # User-site role mappings
└── active_sessions # Current connections
```
所有 VyOS 实例均通过 Web UI 管理——没有硬编码配置。
## 管理多个 VyOS 实例
### 添加更多站点
1. 导航至 **Site Manager**（点击侧边栏中的 VyOS logo）
2. 点击 **“Add Site”** 按钮
3. 输入站点名称和描述
4. 点击 **“Create Site”**
### 向站点添加实例
1. 在 **Site Manager** 中，从列表中选择一个站点
2. 点击 **“Add Instance”** 按钮
3. 填写实例详细信息：
- **Name**：此路由器的友好名称
- **Description**：可选备注
- **Host**：IP 地址或主机名
- **Port**：HTTPS 端口（默认为 443）
- **API Key**：来自 VyOS 配置的密钥
- **Version**：选择 1.4 或 1.5
- **Protocol**：HTTPS（推荐）或 HTTP
4. 点击 **“Complete Setup”**
### 连接到实例
1. 导航至 **Site Manager**
2. 选择一个站点
3. 在任意实例卡片上点击 **“Connect”**
4. VyManager 将测试连接，验证 API 凭证，并将您重定向到控制面板
5. 您现在可以管理该 VyOS 路由器了！
### 在实例之间切换
- 在侧边栏点击 **“Disconnect Instance”**
- 您将返回 **Site Manager**
- 连接到其他实例
## 基于角色的访问控制
VyManager 实现了细粒度的角色访问控制：
| 角色 | 权限 |
|------|-------------|
| **OWNER** | 完全控制：管理站点，添加/编辑/删除实例，授予权限 |
| **ADMIN** | 管理实例，编辑配置，无法删除站点或管理权限 |
| **VIEWER** | 对配置的只读访问 |
角色按站点分配，允许多租户灵活使用场景。
## 版本感知架构
VyManager 使用版本感知的后端架构支持多种 VyOS 版本（1.4、1.5+）。
### 工作原理
后端采用三层架构：
```
Routers (API Endpoints)
↓
Builders (Batch Operations)
↓
Mappers (Version-Specific Commands)
↓
VyOS Device (1.4 or 1.5)
```
每个功能都暴露一个 `/capabilities` endpoint，用于告知前端连接的 VyOS 版本支持哪些功能。前端根据这些 capabilities 有条件地显示/隐藏功能。
## 开发设置
如果您想贡献代码或从源代码运行 VyManager，请按照以下说明操作。
### 前端开发
```
cd frontend
# 安装依赖
npm install
# 运行开发服务器（启用 hot reload）
npm run dev
# 类型检查
npm run type-check
# Lint
npm run lint
# 为生产环境构建
npm run build
```
### 后端开发
```
cd backend
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 带 auto-reload 运行
uvicorn app:app --reload --host 0.0.0.0 --port 8000 --proxy-headers
# 查看 API 文档
# 导航到 http://localhost:8000/docs
```
### 数据库迁移
```
cd frontend
# 在 schema 更改后生成迁移
npx prisma migrate dev --name migration_name
# 应用迁移
npx prisma migrate deploy
# 查看数据库
npx prisma studio
```
## 技术栈
### 前端
- **框架**：Next.js 16 (App Router)
- **语言**：TypeScript
- **样式**：Tailwind CSS v4
- **UI 组件**：shadcn/ui
- **图标**：Lucide React
- **身份验证**：Better-auth
- **状态管理**：Zustand
- **数据库 ORM**：Prisma
### 后端
- **框架**：FastAPI
- **语言**：Python 3.11+
- **VyOS SDK**：pyvyos (custom)
- **数据库**：PostgreSQL
- **数据库驱动**：asyncpg
### 基础设施
- **容器**：Docker & Docker Compose
- **数据库**：PostgreSQL 16
- **容器镜像仓库**：GitHub Container Registry (ghcr.io)
## 安全注意事项
1. **更改默认密钥**：在部署前务必更改 `BETTER_AUTH_SECRET` 和数据库密码
2. **使用 HTTPS**：在生产环境部署中启用 SSL/TLS（使用反向代理如 Nginx 或 Traefik）
3. **保护 API 密钥**：安全存储 VyOS API 密钥，切勿将其提交到 git
4. **数据库备份**：定期备份 PostgreSQL 数据库（`postgres_data` 卷）
5. **网络隔离**：在安全的网络分段中运行 VyManager
6. **定期更新**：保持 VyManager 和 VyOS 为最新版本
## 故障排除
### 自定义 CA 证书
如果您的 VyOS 实例使用由私有 CA（例如 FreeIPA、Active Directory CS、内部 PKI）签名的证书，您可以添加您的 CA 证书，以便在启用“Verify SSL”时 VyManager 能够信任它们。
1. 在 `docker-compose.yml` 旁边创建一个 `certs` 目录：
mkdir certs
2. 将您的 CA 证书复制到其中。文件必须为 PEM 编码且扩展名为 `.crt`：
cp /path/to/my-ca.crt ./certs/
3. 重启后端容器：
docker compose restart backend
后端将在启动时自动导入 `certs` 目录中的所有 `.crt` 文件。您可以添加多个 CA 证书——它们都将被信任。
### 无法连接到 VyOS 实例
1. **检查 API 密钥**：验证 VyOS 中的 API 密钥是否与您的输入一致
2. **检查网络**：确保 VyManager 可以访问 VyOS 的 IP 地址
3. **检查端口**：默认为 443，确认未被防火墙阻止
4. **检查 SSL**：如果使用自签名证书，请将“Verify SSL”设置为 false 或添加您的 CA 证书（参见 [自定义 CA 证书](#custom-ca-certificates)）
### 容器未启动
```
# 检查容器状态和健康状况
docker compose ps
# 检查错误日志
docker compose logs postgres
docker compose logs backend
docker compose logs frontend
```
### 数据库连接失败
```
# 验证 PostgreSQL 状态是否正常
docker compose ps postgres
# 检查 .env 中的 DATABASE_URL 是否与 postgres service 凭据匹配
# 主机名必须是 "postgres"（Docker service 名称），而不是 "localhost"
```
### 前端无法访问后端
- 验证 `.env` 文件中的 `BACKEND_URL=http://backend:8000`（使用 Docker 服务名称）
- 验证 `TRUSTED_ORIGINS` 包含您在浏览器中访问 VyManager 的 URL
- 检查后端容器是否健康：`docker compose ps backend`
## 贡献
1. Fork 该仓库
2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`)
3. 遵循 `CLAUDE.md` 中的架构模式进行更改
4. 在 VyOS 1.4 和 1.5 上进行全面测试
5. 提交您的更改 (`git commit -m 'feat: add amazing feature'`)
6. 推送到该分支 (`git push origin feature/amazing-feature`)
7. 发起 Pull Request
## 许可证
详情请参阅 LICENSE.md。
## 支持
- **问题反馈**：[GitHub Issues](https://github.com/Community-VyProjects/VyManager/issues)
- **Discord**：[加入我们的社区](https://discord.gg/k9SSkK7wPQ)
- **API 文档**：http://localhost:8000/docs (运行时可用)
- **VyOS 文档**：https://docs.vyos.io/
**专为 VyOS 社区倾心打造**
## 快速开始
### 前置条件
- 主机上已安装 **Docker & Docker Compose**
- 已启用 REST API 和 GraphQL 的 **VyOS 路由器**（参见 [步骤 1](#step-1-enable-the-vyos-rest-api)）
## 部署指南
### 步骤 1：启用 VyOS REST API
在部署 VyManager 之前，请在您的 VyOS 路由器上启用 REST API。
通过 SSH 连接到您的 VyOS 路由器并运行：
```
# 进入配置模式
configure
# 创建 API 密钥（将 YOUR_SECURE_API_KEY 替换为一个强壮的随机密钥）
set service https api keys id vymanager key YOUR_SECURE_API_KEY
# 启用 REST 功能（仅限 VyOS 1.5+）
set service https api rest
# 启用 GraphQL（dashboard streaming 需要此功能）
set service https api graphql
# 将 GraphQL 身份验证设置为使用上面定义的 API 密钥
set service https api graphql authentication type key
# 保存并应用
commit
save
exit
```
### 步骤 2：创建项目目录
为 VyManager 创建一个新目录并进入该目录：
```
mkdir vymanager
cd vymanager
```
您将在此目录中创建两个文件：`docker-compose.yml` 和 `.env`。
### 步骤 3：创建 docker-compose.yml
创建一个名为 `docker-compose.yml` 的文件，内容如下：
```
services:
postgres:
image: postgres:16-alpine
container_name: vymanager-postgres
environment:
POSTGRES_USER: vymanager
POSTGRES_PASSWORD: CHANGE_ME_POSTGRES_PASSWORD
POSTGRES_DB: vymanager
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
networks:
- vymanager-network
healthcheck:
test: ["CMD-SHELL", "pg_isready -U vymanager -d vymanager"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
backend:
image: ghcr.io/community-vyprojects/vymanager-backend:beta
container_name: vymanager-backend
ports:
- "8000:8000"
volumes:
- ./certs:/usr/local/share/ca-certificates/custom:ro
env_file:
- .env
restart: unless-stopped
networks:
- vymanager-network
depends_on:
postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/docs"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
frontend:
image: ghcr.io/community-vyprojects/vymanager-frontend:beta
container_name: vymanager-frontend
ports:
- "3000:3000"
env_file:
- .env
depends_on:
backend:
condition: service_healthy
postgres:
condition: service_healthy
restart: unless-stopped
networks:
- vymanager-network
networks:
vymanager-network:
driver: bridge
volumes:
postgres_data:
driver: local
```
### 步骤 4：创建 .env 文件
在同一目录中创建一个名为 `.env` 的文件。后端和前端容器都将从此单一文件中读取配置。
在启动之前，您**必须**更改以下值：
1. **`POSTGRES_PASSWORD`** — 在 `docker-compose.yml` 和下面的 `DATABASE_URL` 中**同时**修改；它们必须保持一致。生成方式：`openssl rand -hex 32`
2. **`BETTER_AUTH_SECRET`** — 用于签名和验证会话 token；在文件中会出现**两次**（每个服务一次），且两处的值必须**相同**。生成方式：`openssl rand -base64 32`
3. **`SSH_ENCRYPTION_KEY`** — 用于加密静态存储的 SSH 私钥。生成方式：`openssl rand -hex 32`
4. **`BETTER_AUTH_URL` / `NEXT_PUBLIC_APP_URL`** — 将 `标签：Docker, Docker Compose, GraphQL, IT运维, NPMD, REST API, SDN控制器, Socks5代理, VyOS, Web管理界面, 企业级网络, 多站点管理, 安全防御评估, 广域网管理, 开源网络工具, 测试用例, 网络基础设施, 网络自动化, 网络部署, 网络配置管理, 自动化攻击, 请求拦截, 路由器管理, 逆向工具, 集中化管理