# admin-platform-template

**Repository Path**: dogoo/admin-platform-template

## Basic Information

- **Project Name**: admin-platform-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Admin AI Platform

基于 FastAPI + Vue 3 的 AI 管理平台，提供统一的认证、权限管理与服务注册中心。

---

## 目录

- [架构概览](#架构概览)
- [功能模块](#功能模块)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [API 概览](#api-概览)
- [开发指南](#开发指南)
- [部署说明](#部署说明)
- [常见问题](#常见问题)

---

## 架构概览

项目采用**平台架构**，由集成平台统一处理所有外部请求：

```
外部流量（浏览器 / API 调用）
         │
         ▼  端口 9102（统一入口）
┌───────────────────────────────────────┐
│          集成平台（system）             │
│  · JWT 认证 & RBAC 权限管理           │
│  · 监控仪表盘                          │
└───────────────────────────────────────┘
```

---

## 功能模块

### 集成平台（system）

| 功能 | 说明 |
|------|------|
| **JWT 认证** | 登录/登出，多用户并发支持，验证码防暴力破解 |
| **用户管理** | 用户增删改查、启用/停用、密码重置 |
| **角色与权限** | RBAC 角色配置，按角色分配菜单与按钮级权限 |
| **菜单配置** | 权限与前端菜单联动，支持导入/导出，无需改代码 |
| **仪表盘** | 平台统计入口 |

---

## 项目结构

```
admin-ai-platform/
│
├── venv/                          # 统一虚拟环境目录
│   └── platform/                  # 集成平台虚拟环境
│
├── build_scripts/                 # 构建脚本目录
│   ├── build.sh                   # 普通版本构建脚本
│   └── build-cuda.sh              # CUDA版本构建脚本
│
├── system/                        # 集成平台（端口 9102）
│   ├── main-system.py             # 入口
│   ├── config.yaml                # 平台配置（数据库 / 端口）
│   ├── requirements.txt           # 平台依赖
│   ├── auth_models.py             # 用户/角色/权限 ORM 模型
│   ├── routes/                    # auth / user / role / permission / dashboard
│   └── shared/                    # 公共工具：auth / config
│
├── web/                           # 前端 Vue 3 SPA
│   ├── src/
│   │   ├── api/                   # 按模块封装的接口（auth / user / role / registry …）
│   │   ├── views/                 # 页面（dashboard / system）
│   │   ├── router/                # Vue Router（动态路由 + 权限守卫）
│   │   └── store/                 # Pinia 状态（user / theme / tabs / permission）
│   └── vite.config.js
│
├── scripts/
│   ├── start.sh                   # 启动集成平台
│   └── stop.sh                    # 停止集成平台
│
├── config/
│   └── system/                    # 集成平台配置
│       └── config.yaml
│
├── uploads/                       # 上传文件
├── data/                          # 运行时数据（SQLite 文件 / PID 文件）
│   ├── pids/                      # PID 文件
│   └── system/                    # 集成平台 SQLite
├── logs/                          # 日志
│   └── platform.log               # 集成平台日志
└── docs/                          # 设计文档
```

---

## 快速开始

### 环境要求

| 依赖 | 版本 | 说明 |
|------|------|------|
| Python | 3.10+ | |
| Node.js | 18+ | 仅前端构建时需要 |
| PostgreSQL | 13+ | 推荐；也可使用 SQLite（无需安装） |

---

### 方式一：一键启动（推荐）

```bash
git clone <repository-url>
cd admin-ai-platform

# 构建虚拟环境
bash build_scripts/build.sh

# 前端依赖
cd web && npm install && cd ..

# 修改 config/system/config.yaml（数据库连接等），然后启动
bash scripts/start.sh
```

启动后访问 `http://localhost:9102/hzclaw/`（前端 `base` 为 `/hzclaw/`），默认账号 `admin` / `admin123`，**首次登录后请立即修改密码**。

停止所有服务：

```bash
bash scripts/stop.sh
```

#### 构建脚本说明

| 脚本 | 说明 |
|------|------|
| `build_scripts/build.sh` | 普通版本 |
| `build_scripts/build-cuda.sh` | CUDA版本 |

**构建脚本用法：**

```bash
# 构建服务
bash build_scripts/build.sh

# 更新已存在虚拟环境的依赖
bash build_scripts/build.sh --update
```

---

### 方式二：单独启动（开发调试）

```bash
# 集成平台
source venv/platform/bin/activate && PYTHONPATH=system python system/main-system.py
```

---

### 前端开发

```bash
cd web
npm install
npm run dev      # 开发模式，代理到 9102
```

生产构建（产物由集成平台托管）：

```bash
cd web
npm run build
# 将 web/dist/ 内容复制到 system/static/
cp -r dist/* ../system/static/
```

---

## 配置说明

服务配置统一放在项目根目录 `config/` 下：

| 服务 | 配置文件 | 端口 |
|------|----------|------|
| 集成平台 | `config/system/config.yaml` | 9102 |

### 数据库配置

```yaml
sqlalchemy:
  mode: sqlite          # 本地轻量，无需额外数据库服务
  db_path: data/system/config.db
```

或使用 PostgreSQL：

```yaml
sqlalchemy:
  mode: pgsql
  host: 127.0.0.1
  port: 5432
  database: postgres
  user: postgres
  password: your_password
  db_schema: public
```

---

## API 概览

所有外部请求统一通过集成平台（端口 9102）访问。前端与网关约定 **API 根路径为 `/hzclaw/api`**（见 `web/src/router/index.js` 中 `API_BASE`）。集成平台 Swagger：`http://localhost:9102/docs`。

### 集成平台接口

| 类别 | 路径 |
|------|------|
| 认证 | `POST /hzclaw/api/auth/login`、`POST /hzclaw/api/auth/logout`、`GET /hzclaw/api/auth/profile` |
| 仪表盘 | `GET /hzclaw/api/dashboard/stats` |
| 用户管理 | `GET/POST/PUT/DELETE /hzclaw/api/admin/users` |
| 角色管理 | `GET/POST/PUT/DELETE /hzclaw/api/admin/roles` |
| 权限菜单 | `GET/POST/PUT/DELETE /hzclaw/api/admin/permissions` |

---

## 开发指南

### 添加新菜单

1. 登录后台 → 「系统配置」→「菜单配置」→ 新增菜单项，填写 `code`、`path`、`component` 等。
2. 在 `web/src/router/index.js` 的 `asyncRouteMap` 中注册对应 Vue 组件。
3. 为需要访问的角色分配该菜单权限。

---

## 部署说明

### systemd 服务示例

```ini
# /etc/systemd/system/ai-platform.service
[Unit]
Description=AI Platform - Integration System
After=network.target postgresql.service

[Service]
Type=simple
User=ai
WorkingDirectory=/opt/admin-ai-platform
Environment="PYTHONPATH=/opt/admin-ai-platform/system"
ExecStart=/opt/admin-ai-platform/venv/platform/bin/python system/main-system.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

### Nginx 反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:9102;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }
}
```

### 日志

日志位于 `logs/` 目录：

| 文件 | 对应服务 |
|------|----------|
| `logs/platform.log` | 集成平台 |

日志按天滚动（`TimedRotatingFileHandler`），最多保留 5 天。

---

## 常见问题

**Q：前端页面白屏或 404？**
A：确认 `web/` 已构建（`npm run build`）并将 `dist/` 内容复制到 `system/static/`；或在开发模式下使用 `npm run dev`。

**Q：如何修改默认端口？**
A：修改 `config/system/config.yaml` 中的 `server.host` 和 `server.port`。