Maas-Agent

ZhAgentOS 2.0

企业级智能体平台 —— 强大易用的 AI Agent 构建与管理系统。

技术栈

层级	技术
后端	Python 3.11 + Django 5.2 + DRF
前端	Vue 3 + TypeScript + Vite 6 + Element Plus
数据库	PostgreSQL 17 + pgvector
缓存	Redis 7
任务队列	Celery + Redis
包管理	uv (Python) + npm (Node.js)

三端架构

项目前端分为三个独立的 SPA，共享同一套后端 API 和前端代码库：

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Admin 管理端   │     │  Builder 构建端   │     │   Chat 访问端   │
│   /admin/       │     │  /builder/       │     │   /chat/        │
│   端口 3000     │     │  端口 3002       │     │   端口 3001     │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                        │
         └───────────────────────┼────────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │     Django REST API     │
                    │        :8080            │
                    └────────────┬────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
        ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
        │ PostgreSQL │     │   Redis   │     │  Celery   │
        │   :5433    │     │   :6379   │     │  Worker   │
        └───────────┘     └───────────┘     └───────────┘

Admin 管理端 (/admin/)

平台管理员使用，负责系统级管理：

• 用户管理（创建、角色分配、权限控制）
• 工作区管理
• 角色权限管理
• 资源管理与授权
• 系统设置（主题、认证、邮件）
• 操作日志

Builder 构建端 (/builder/)

智能体开发者使用，负责资源构建：

• 智能体（应用）管理 —— 创建、配置、发布
• 知识库管理 —— 文档上传、向量化、Q&A 管理
• 工具管理 —— 自定义工具、MCP 工具
• 模型管理 —— 接入 20+ 模型供应商
• 工作流编排 —— 可视化流程编辑器（LogicFlow）
• 触发器管理

Chat 访问端 (/chat/)

终端用户使用，访问发布的智能体：

• PC 端对话界面
• 移动端对话界面
• 嵌入式对话组件
• 分享对话链接
• 用户登录（支持钉钉、飞书、企业微信扫码）

项目结构

zhagent/
├── main.py                    # 后端入口（start/dev/upgrade_db/collect_static）
├── config.yml                 # 运行时配置（DB、Redis、语言等）
├── pyproject.toml             # Python 依赖（uv 管理）
├── startTools.bat             # Windows 服务管理菜单
├── apps/                      # Django 后端
│   ├── maxkb/                 #   项目核心（settings、urls、wsgi）
│   ├── users/                 #   用户管理
│   ├── application/           #   智能体/应用管理 + 工作流引擎
│   ├── knowledge/             #   知识库（向量搜索、文档处理）
│   ├── models_provider/       #   模型供应商集成（20+ 供应商）
│   ├── tools/                 #   工具管理
│   ├── chat/                  #   聊天 API
│   ├── trigger/               #   触发器系统
│   ├── oss/                   #   文件存储
│   ├── system_manage/         #   系统管理
│   ├── folders/               #   文件夹管理
│   ├── common/                #   公共模块（认证、缓存、中间件等）
│   └── static/                #   构建产物（collect_static 输出）
└── ui/                        # Vue 前端（三端完全独立）
    ├── package.json           #   便捷脚本集合
    ├── admin/                 #   管理端（完全独立）
    │   ├── package.json       #     管理端依赖
    │   ├── admin.html         #     入口 HTML
    │   ├── vite.config.ts     #     Vite 构建配置
    │   ├── env/.env           #     环境变量（port 3000）
    │   └── src/               #     管理端源代码
    │       ├── main.ts        #       入口文件
    │       ├── App.vue        #       根组件
    │       ├── router/        #       路由（system 模块）
    │       ├── views/         #       页面（system, login, error）
    │       ├── api/           #       API 客户端
    │       ├── stores/        #       状态管理
    │       ├── components/    #       共享组件副本
    │       ├── styles/        #       样式副本
    │       ├── locales/       #       国际化副本
    │       ├── utils/         #       工具函数副本
    │       └── ...
    ├── builder/               #   构建端（完全独立）
    │   ├── package.json       #     构建端依赖
    │   ├── builder.html       #     入口 HTML
    │   ├── vite.config.ts     #     Vite 构建配置
    │   ├── env/.env           #     环境变量（port 3002）
    │   └── src/               #     构建端源代码
    │       ├── builder.ts     #       入口文件
    │       ├── App.vue        #       根组件
    │       ├── router/        #       路由（application, knowledge, tool, model, trigger）
    │       ├── views/         #       页面（application, knowledge, tool, model 等）
    │       ├── api/           #       API 客户端
    │       ├── stores/        #       状态管理
    │       ├── workflow/      #       工作流编辑器
    │       ├── components/    #       共享组件副本
    │       ├── styles/        #       样式副本
    │       ├── locales/       #       国际化副本
    │       ├── utils/         #       工具函数副本
    │       └── ...
    └── chat/                  #   访问端（完全独立）
        ├── package.json       #     访问端依赖
        ├── chat.html          #     入口 HTML
        ├── vite.config.ts     #     Vite 构建配置
        ├── env/.env           #     环境变量（port 3001）
        └── src/               #     访问端源代码
            ├── chat.ts        #       入口文件
            ├── App.vue        #       根组件
            ├── router/        #       路由（chat 模块）
            ├── views/         #       页面（chat 对话界面）
            ├── api/           #       API 客户端
            ├── stores/        #       状态管理（chat-user）
            ├── components/    #       共享组件副本
            ├── styles/        #       样式副本
            ├── locales/       #       国际化副本
            ├── utils/         #       工具函数副本
            └── ...

环境依赖

依赖	版本	说明
Python	3.11+	推荐用 uv 管理
Node.js	18+	npm 管理前端依赖
PostgreSQL	14+	需要 pgvector 扩展
Redis	6+	缓存 + Celery broker

快速启动（开发环境）

1. 克隆项目

git clone <repo-url> zhagent
cd zhagent

2. 安装 Python 依赖

uv sync

3. 安装前端依赖

cd ui && npm install && cd ..

4. 配置数据库

复制配置模板并编辑：

cp config_example.yml config.yml

编辑 config.yml：

DB_HOST: 127.0.0.1
DB_PORT: 5432          # PostgreSQL 端口
DB_USER: postgres
DB_PASSWORD: your_password
DB_NAME: maxkb
REDIS_HOST: 127.0.0.1
REDIS_PORT: 6379
REDIS_PASSWORD: ''
REDIS_DB: 0
DEBUG: true
LANGUAGE_CODE: zh-CN

5. 初始化数据库

确保 PostgreSQL 已启动并创建了数据库：

CREATE DATABASE maxkb;
CREATE EXTENSION IF NOT EXISTS vector;

6. 启动服务

# 终端 1：Celery Worker
python main.py dev celery

# 终端 2：Django Web（端口 8080）
python main.py dev web

# 终端 3：管理端（端口 3000）
cd ui && npm run dev

# 终端 4：构建端（端口 3002）
cd ui && npm run builder

# 终端 5：访问端（端口 3001）
cd ui && npm run chat

或者使用 Windows 服务管理菜单：

startTools.bat
# 选择 1 启动全部服务

7. 登录

• 管理端：http://localhost:3000/admin/
• 构建端：http://localhost:3002/builder/
• 访问端：http://localhost:3001/chat/<accessToken>

默认账号：admin@zhagent.com 默认密码：ZhAgent@980123

构建部署

Docker 部署（推荐）

# 1. 构建前端
bash build-frontend.sh

# 2. 启动全部服务
docker compose up -d

# 3. 查看日志
docker compose logs -f

# 4. 停止服务
docker compose down

数据持久化目录（挂载到本地磁盘）：

• ./data/postgresql — PostgreSQL 数据
• ./data/redis — Redis 数据
• ./data/uploads — 上传文件

修改默认密码：创建 .env 文件

DB_PASSWORD=your_secure_password

开发模式（仅数据库和缓存）

# 启动 PostgreSQL + Redis
docker compose -f docker-compose.dev.yml up -d

# 启动后端
python main.py dev celery  # 终端 1
python main.py dev web     # 终端 2

# 启动前端
cd ui && npm run dev:all

手动部署

# 构建前端
cd ui && npm run install:all
npm run build:admin
npm run build:builder
npm run build:chat

# 收集静态文件到 Django
python main.py collect_static

# 启动生产服务（gunicorn + celery）
python main.py start all

前端开发指南

三端完全独立

三个 SPA 各自独立，拥有完整的代码副本：

• ui/admin/ — 管理端（系统管理、用户管理、角色权限）
• ui/builder/ — 构建端（智能体、知识库、工具、模型、工作流）
• ui/chat/ — 访问端（对话界面、用户登录）

开发命令

# 安装依赖
cd ui && npm run install:all

# 启动单个端
cd ui && npm run dev:admin    # 管理端 :3000
cd ui && npm run dev:builder  # 构建端 :3002
cd ui && npm run dev:chat     # 访问端 :3001

# 同时启动三端
cd ui && npm run dev:all

新增页面

• 管理端页面：添加到 ui/admin/src/router/modules/system.ts
• 构建端页面：添加到 ui/builder/src/router/modules/ 对应的模块
• 访问端页面：添加到 ui/chat/src/router/chat/routes.ts

API 请求

每个端通过 window.MaxKB.prefix 动态设置 API 基础路径：

• 管理端：/admin/api
• 构建端：/builder/api
• 访问端：/chat/api

注意事项

由于三端代码完全独立，修改共享代码（如组件、样式、工具函数）时需要同步修改三个目录。建议：

1. 先在一个端修改并验证
2. 然后复制到其他两个端
3. 或使用脚本批量同步

后端开发指南

Django Apps

App	路径前缀	用途
users	/admin/api/	用户管理
system_manage	/admin/api/	系统管理
application	/builder/api/	智能体管理
knowledge	/builder/api/	知识库管理
tools	/builder/api/	工具管理
models_provider	/builder/api/	模型管理
trigger	/builder/api/	触发器
chat	/chat/api/	聊天 API
oss	共用	文件存储

新增 Django App

1. 在 apps/ 下创建 app 目录
2. 添加到 apps/maxkb/settings/base/web.py 的 INSTALLED_APPS
3. 在 apps/maxkb/urls/web.py 中注册路由到对应的 API 前缀
4. 运行 python main.py upgrade_db 创建数据库表

配置系统

配置优先级：

1. 环境变量 MAXKB_*（需设置 MAXKB_CONFIG_TYPE=ENV）
2. YAML 文件（config.yml > config.yaml > config_example.yml）
3. 默认值（apps/maxkb/conf.py 中 Config.defaults）

模型供应商

支持 20+ 模型供应商，位于 apps/models_provider/impl/：

OpenAI、Anthropic、DeepSeek、Gemini、Qwen、Ollama、Azure、AWS Bedrock、阿里云百炼、火山引擎、腾讯云、SiliconFlow、Kimi、文心一言、讯飞星火、本地模型、vLLM、Xinference、Docker AI、Regolo

License

MIT License