DjangoBaseAi
Django 通用底座:在 Django + DRF 之上提供企业级底座(认证、RBAC、组织架构、操作/登录日志、文件与消息等),产品业务(对话、文档、PPT、IM 协作等)放在消费方仓库,不要写进本包。
给 AI / 后续模块开发:先读 AGENT.md。
- 包名:
django-base-ai(导入名:django_base_ai) - 快速开始:快速开始
- 多租户(默认关闭):多租户
- 插件中心:插件中心
- OAuth2 统一登录门户:OAuth2 第三方接入
- 个人中心授权码:个人中心授权码 ac_code
快速开始(首次使用)
使用 pip 安装,在新建或已有 Django 项目中按文档配置即可,无需克隆仓库、无需 MySQL/Redis(SQLite + 内存缓存)。
pip install django-base-ai
django-admin startproject myproject && cd myproject
然后在项目的 settings.py 中先 from django_base_ai.settings import *,再按本文「快速开始」配置数据库(SQLite)、缓存(内存)、INSTALLED_APPS、MIDDLEWARE、路由等;执行 migrate、runserver 即可访问。建议再执行 python manage.py init 初始化菜单/角色/字典。对话与 PPT HTTP 接口在产品仓库,不在本包。
发布时前端:在本仓执行 ./build.sh 会自动在同级 ../DjangoBaseAiWeb(或本仓 ./web)跑 npm run build:pack,再拷入 django_base_ai/adminweb/ 打进 wheel。不必再手动打包/拷贝。跳过重编:SKIP_FRONTEND_BUILD=1 ./build.sh。
管理后台(零配置):wheel 内已打入 DjangoBaseAIWeb 生产构建。只要 INSTALLED_APPS 含 django_base_ai.system,启动后打开:
http://ip:port/admin/ # 管理端 SPA
http://ip:port/admin/#/login # 登录页(hash 路由)
接口仍走同源 http://ip:port/base/api/system/...,不必再单独部署前端或配 nginx 静态目录。
配置参数关系与效果
底座配置写在业务项目的 settings.py(先 from django_base_ai.settings import *,再按需覆盖)。下面按「谁依赖谁 → 能得到什么」说明;未列出的项保持底座默认即可跑通。
1. 管理端页面(adminweb)
| 参数 | 默认 | 依赖关系 | 效果 |
|---|---|---|---|
django_base_ai.system ∈ INSTALLED_APPS |
必选 | 触发 AppConfig.ready() |
启动时尝试自动挂载管理端路由 |
ADMINWEB_AUTO_MOUNT |
True |
依赖上一项;且 wheel 内存在 django_base_ai/adminweb/index.html |
True:自动挂到根 URLconf;False:不挂,需自行 include |
ADMINWEB_MOUNT_PATH |
"/admin/" |
仅在自动挂载开启时生效 | 浏览器访问前缀;/admin 会 302 到带尾斜杠的路径 |
包内 adminweb/ |
发布机 build:pack + bundle 打进 wheel |
无产物则跳过挂载并打日志 | 提供 index.html 与 `static/js |
关系简述:
pip 安装(含 adminweb)
→ INSTALLED_APPS 含 django_base_ai.system
→ ADMINWEB_AUTO_MOUNT=True(默认)
→ 挂载 ADMINWEB_MOUNT_PATH(默认 /admin/)
→ 打开 /admin/ 即管理端;API 仍用 /base/api/system/
关闭示例:
ADMINWEB_AUTO_MOUNT = False
# 或改挂载前缀:
# ADMINWEB_MOUNT_PATH = "/console/"
2. 接入底座 API 的最小三角
| 参数 / 配置 | 默认或示例 | 依赖关系 | 效果 |
|---|---|---|---|
from django_base_ai.settings import * |
— | 最先执行 | 带入 DRF / JWT / 分页 / 认证 / 异常处理等默认 |
INSTALLED_APPS 含 django_base_ai.system |
— | 依赖 Django 应用加载 | 模型、迁移、管理命令、/admin/ 自动挂载 |
urls.py:path("base/api/system/", include("django_base_ai.system.urls")) |
— | 与上一项配合 | 暴露登录、用户/角色/部门、菜单、字典等 HTTP API |
SECRET_KEY / 环境变量 DJANGO_SECRET_KEY |
开发有占位;ENV=pro 必填真密钥 |
JWT / session 签名 | 多应用共用同一密钥可共享登录态;生产禁止 django-insecure |
缺路由则只有页面没有接口;缺 system 应用则页面也不会自动挂载。
未匹配的 /base/api/ 即使 DEBUG=True 也返回 JSON 404,而不是 Django 技术黄页。非 API 页面(例如 /admin/)仍保留原来的 DEBUG 黄页。
| 参数 | 默认 | 效果 |
|---|---|---|
API_JSON_404_ENABLED |
True |
False 时不再改写 404,API 路径也会回到 Django 的 HTML 404 |
API_JSON_404_PREFIXES |
["/base/api/"] |
要改写成 JSON 的前缀。覆盖此列表会替换默认值 |
API_JSON_404_EXTRA_PREFIXES |
[] |
只追加、不替换。产品前缀写在宿主,例如 ["/docs/app/"] |
django_base_ai.system 就绪时,若 MIDDLEWARE 里还没有 ApiJson404Middleware,会插到 CORS 之后、CommonMiddleware 之前。JSON 体与底座 Http404 口径一致:{"code": 400, "data": null, "msg": "接口地址不正确"},HTTP 状态为 404。
3. 运行环境与数据面
| 参数 | 典型值 | 依赖关系 | 效果 |
|---|---|---|---|
DATABASES |
SQLite 或 MySQL | ORM / 迁移 | 存用户、角色、菜单、日志等 |
REDIS_MODE / CACHES / CHANNEL_LAYERS |
memory 或 Redis |
缓存、Channels、部分限流 | quickstart 用内存即可;生产建议 Redis |
DISPATCH_DB_TYPE |
"memory" / 库 |
字典与系统配置调度 | 控制配置缓存后端 |
CORS_ALLOWED_ORIGINS |
同源可空;跨域需显式列表 | 浏览器跨域调 API | 管理端与 API 不同源时必配 |
ALLOWED_HOSTS |
开发可用 ["*"] |
Django 主机校验 | 生产必须写成真实域名/IP |
4. 初始化与权限相关开关
| 参数 | 默认 | 效果 |
|---|---|---|
python manage.py migrate |
— | 创建底座表结构 |
python manage.py init |
— | 导入菜单 / 角色 / 字典等 fixtures |
INITIALIZE_DEPT_AND_USERS |
True |
init 时是否初始化部门与用户 |
INITIALIZE_ALL_USERS |
True |
False 时 init 只保留第一个用户(admin) |
LICENSE_VERIFY_ENABLE |
False |
打开后按 License 拦截;/admin、/healthy 等在默认排除列表 |
5. 运维页(可选)
| 参数 | 默认 | 效果 |
|---|---|---|
CELERY_OPS_QUEUES |
["celery", "vector", "skill"] |
管理端「任务状态」巡检的队列名 |
SUPERVISOR_SOCKET |
/var/run/supervisor.sock |
「进程守护」连本机 Supervisor |
SUPERVISOR_CONTROL_ENABLED |
True |
是否允许启停进程 |
SUPERVISOR_NODES / SUPERVISOR_AGENT_TOKEN |
空 | 多机 Supervisor 代理查询 |
这些只影响管理端运维菜单对应的 API,不影响 /admin/ 页面能否打开。
痛点与解决方案
| 痛点 | 解决方案 |
|---|---|
| 想快速接入大模型能力,又不想从零搭权限与基础 | 底座提供认证、RBAC、日志与 utils.ai 客户端;对话/PPT HTTP 由产品 app 接入 |
| 企业系统权限需求复杂,自建 RBAC 成本高、易遗漏 | 完整 RBAC:用户、角色、部门、菜单、按钮权限、接口白名单、数据权限过滤,开箱即用 |
| 国内大型企业组织架构明确、层级多、权限要求严 | 部门树、懒加载、数据权限按部门/角色过滤,贴合「组织架构清晰、权限分级严格」的国内企业场景 |
| 每个项目重复实现登录、字典、文件、日志等基础能力 | 统一认证(JWT、单点登录、验证码)、字典/系统配置、文件与文件夹、操作日志、消息中心等一应俱全 |
| 希望快速接入企业规范,而非从零搭架子 | 安装依赖、配置 INSTALLED_APPS 与路由后,一键集成到现有 Django 项目,无需重写权限与基础模块 |
技术信息
- Python:3.9+
功能概览
主推:AI 能力
| 模块 | 说明 |
|---|---|
| AI 客户端 | django_base_ai.utils.ai:多供应商 Chat / 生图,供产品 app 调用 |
配置 AI 供应商(见 conf/env.py 或文档)后即可使用,无需改业务代码。
底座核心(通用能力,支撑 AI 与业务)
| 模块 | 说明 |
|---|---|
| 认证 | JWT(SimpleJWT)、单点/第三方登录、验证码、登出、Token 刷新 |
| RBAC | 用户、角色、部门、菜单、按钮权限、接口白名单、数据权限过滤 |
| 系统配置 | 字典、系统配置键值、调度中心(dispatch)、初始化接口 |
| 审计与日志 | 操作日志、登录日志、日志文件分析/下载/实时 tail |
| 文件与存储 | 文件夹、文件上传/列表/下载、导入导出(Excel) |
| 消息与协作 | 消息中心、常用联系人、协作人、我的上级、WebSocket |
| 任务与配置 | 基础任务、任务历史、应用/标签、数据可视化配置 |
| 工具 | 统一 JSON 响应、分页、异常处理、权限校验、加解密、节假日、健康检查等 |
其他扩展(按需使用)
| 模块 | 说明 |
|---|---|
| 数据分析 | 通用分析视图(base_analyze) |
| 数据可视化 | 看板/大屏配置(datav) |
IM 协作会话、员工服务、CMDB 不在本包;由消费方(如 DocsAI)自行提供。
统一响应格式
除流式接口与 WebSocket 外,接口均采用以下 JSON 结构。
成功
分页列表(list 等):
{
"code": 2000,
"msg": "success",
"data": {
"page": 1,
"limit": 10,
"total": 100,
"is_next": true,
"is_previous": false,
"data": [ /* 当前页列表 */ ]
}
}
单条/非分页(retrieve、create、update、部分自定义接口):
{
"code": 2000,
"msg": "success",
"data": { /* 单条对象或业务结构 */ }
}
错误
{
"code": 400,
"msg": "错误说明",
"data": null
}
业务错误码可能为 4xxx(如 4000 登录失败、401 未授权等),status 为 HTTP 状态码。
暴露的 API 接口
以下路径均以 /base/api/system/ 为前缀(由主项目 urls.py 挂载决定)。
认证与登录(无需 Token)
| 方法 | 路径 | 说明 | 返回值 |
|---|---|---|---|
| POST | login/ |
用户名密码登录(可选验证码;多租户开启时须 tenant_code) |
{ code, msg, data: { access, refresh, name, userId, … } } |
| POST | sign_login/ |
企业 4A / 第三方 code 换票 | 同上结构 |
| POST | custome_login/ |
自定义登录 | 同上结构 |
| POST | user/ac_code_to_login/ |
个人中心授权码换 JWT(见下文) | 同上结构;login_type=4 |
| GET | oauth/client_meta/ |
OAuth 应用公开元数据 | title / icon / scopes / oauth_auth_mode / redirect_uri_allowed |
| POST | oauth/authorize/ |
已登录用户签发 OAuth code(须白名单;授权绑定须 consent) |
{ code } |
| POST | oauth/token/ |
OAuth code + 密钥换 access_token |
{ access_token, token_type, expires_in } |
| GET | oauth/userinfo/ |
Bearer OAuth AT 取用户信息 | 用户摘要 |
| GET | captcha/ |
获取图形验证码 | data: { key, image_base }(base64 图片) |
| GET | init/dictionary/ |
初始化字典(query: dictionary_key,all 或父 value) | 分页或列表格式,data 为字典项列表 |
| GET | init/settings/ |
初始化系统配置(query: key,可选,多 key 用 | 分隔) | data: 键值对配置 |
Token 与登出(需 Token)
| 方法 | 路径 | 说明 | 返回值 |
|---|---|---|---|
| POST | token/refresh/ |
刷新 JWT | { code, msg, data: { access, refresh } }(注意:序列化器可能返回 code=0,视图再封装为 Response) |
| POST | logout/ |
登出,使当前 token 失效 | { code: 2000, msg: "注销成功", data: null } |
系统配置扩展
| 方法 | 路径 | 说明 | 返回值 |
|---|---|---|---|
| PUT | system_config/save_content/ |
保存配置内容 | DetailResponse |
| GET | system_config/get_association_table/ |
获取关联表配置 | 分页格式,data.data 为表数据 |
| GET | system_config/get_table_data/<pk>/ |
获取指定表数据 | DetailResponse |
| GET | system_config/get_relation_info/ |
查询关联模板信息(query: varName, table, relationIds) | DetailResponse 或 ErrorResponse |
| GET | system_config/check/ |
项目安全依赖检查(Admin) | data: { timestamp, pkg_count, vulnerabilities_count, vulnerabilities } |
| GET | system_config/vulnerabilities_count/ |
漏洞包总数(Admin) | data: 数字 |
部门扩展
| 方法 | 路径 | 说明 | 返回值 |
|---|---|---|---|
| GET | dept_lazy_tree/ |
部门懒加载树 | DetailResponse,树形结构 |
节假日与 WebSocket
| 方法 | 路径 | 说明 | 返回值 |
|---|---|---|---|
| GET | holiday/ |
节假日(匿名,无需 Token;query: type=0 当天/1 指定日期/2 全部,day 为日期) | data: 当天信息或 day_infos 列表 |
| GET | ws |
WebSocket 连接(消息中心等) | 非 JSON,WebSocket 协议 |
资源型 CRUD(标准 REST)
以下资源均支持:GET 列表(分页)、POST 创建、GET /{id}/ 详情、PUT/PATCH /{id}/ 更新、DELETE /{id}/ 删除。返回格式见「统一响应格式」。
| 资源路径 | 说明 |
|---|---|
menu/ |
菜单 |
menu_button/ |
菜单按钮 |
role/ |
角色 |
dept/ |
部门 |
user/ |
用户 |
operation_log/ |
操作日志 |
dictionary/ |
字典 |
area/ |
区域 |
folder/ |
文件夹 |
file/ |
文件 |
api_white_list/ |
接口白名单 |
system_config/ |
系统配置(CRUD) |
message_center/ |
消息中心 |
message_center_target_user/ |
消息中心目标用户 |
frequently_used_contacts/ |
常用联系人 |
datav/ |
数据可视化配置 |
task/ |
基础任务 |
task_run_history/ |
任务运行历史 |
apps/ |
应用管理(含 OAuth appid / 白名单) |
plugin/ |
插件中心(catalog / upload / install / enable…,见插件中心) |
tags/ |
标签 |
collaborator/ |
协作人 |
my_superiors/ |
我的上级 |
login_log/ |
登录日志 |
base_analyze/ |
数据分析(ViewSet,多为 GET 自定义 action) |
对话 / PPT HTTP 路由不在本包,见消费方(如 DocsAI AIChat)。本包提供 django_base_ai.utils.ai 客户端。
其他资源上的自定义 Action(选列)
- dictionary:
GET dictionary/dictionary_tree/?value=xxx→ 指定节点递归树,DetailResponse。 - role:
role/role_list/、role/role_id_list/、role/tree/、role/open/等,见role.py。 - user:
user/user_list/、user/export/、user/import/、user/update_user_info/、user/reset_password/、user/change_avatar/等,见user.py。 - user AI 记忆(仅当前登录用户,不进登录/用户列表):
| 方法 | 路径 | 说明 | 返回值 |
|---|---|---|---|
| GET | user/ai_memory/ |
读取本人长期记忆;无记录时 content=""、version=0 |
data: { user_id, filename, content, version, update_datetime },filename 为 USER_AI_MEMORY_{user_id}.md |
| PUT/PATCH | user/ai_memory/ |
写入 Markdown(≤64KB)。可选 version 做乐观锁,冲突返回 code=409 |
同上,version 加一 |
| DELETE | user/ai_memory/ |
清空正文(保留行,version 加一)。可选带 version |
同上 |
Python 侧注入 prompt:get_user_ai_memory_markdown(user) / format_user_ai_memory_for_prompt(user)。记忆与空间级 agent_memory 分层,不写在 Users 上。
- menu:
menu/tree/等。 - dept:
dept_lazy_tree/已单独列出;另有dept/tree/、dept/export/、dept/import/等。 - file:上传、下载、自定义 action 见
file_list.py。 - message_center:已读、未读、推送等 action。
- task:
task/run/、task/update_task_status/等。 - login_log:自定义统计等 action。
- base_analyze:多种 GET/POST 分析接口(AllowAny),见
base_analyze.py。
具体请求参数与字段以各 ViewSet 内 docstring 及 serializer 为准。
安装
首次使用:直接执行 pip install django-base-ai,再按本文「快速开始」在项目中完成配置即可。
Windows / Linux 兼容:uwsgi、supervisor 只在 Linux/macOS 安装。pyproject.toml 和 requirements.txt 都带 sys_platform != "win32",Windows 上 pip install django-base-ai 或 pip install -r requirements.txt 会跳过它们。requirements.txt 由 ./build.sh 按当前环境重新生成。Windows 本地开发用 python manage.py runserver 或 daphne。
从源码开发/可编辑安装(本仓库克隆后):
pip install -r requirements.txt
# 或 pip install -e ".[dev]"
[dev] 会安装 pytest、pytest-django、ruff。Linux 生产环境可额外执行 pip install django-base-ai[deploy] 显式安装 uwsgi/supervisor。
本地一键启动
./dev_run.sh 只启动本仓库 Django(默认 :8075)。管理端请到同级 DjangoBaseAiWeb 单独启动。
./dev_run.sh
# SQLite 快速开始(无需 MySQL/Redis)
ENV=quickstart ./dev_run.sh
# 改端口
BACKEND_PORT=8075 ./dev_run.sh
访问:http://127.0.0.1:8075/。
在项目中使用(一键集成)
安装 DjangoBaseAi 后,按以下步骤即可将 AI 能力与底座(RBAC、组织架构与基础能力) 一键集成到现有 Django 项目。
- 安装:将本仓库可编辑安装或打包后安装到目标 Django 项目环境。
- 配置:在目标项目
settings.py中:- 将
django_base_ai.system加入INSTALLED_APPS - 按需配置数据库、缓存、JWT、CORS 等(可参考本仓库
django_base_ai/settings.py) - 自定义异常处理:
EXCEPTION_HANDLER = "django_base_ai.utils.exception.custom_exception_handler" - 主推 AI:在
conf/env.py或环境中配置AI_DEFAULT_PROVIDER与对应AI_*_API_KEY(如 DeepSeek/腾讯/OpenAI),即可使用对话、PPT、文本润色等接口。
- 将
- 路由:在目标项目
urls.py中挂载系统 API(管理端页面默认自动挂到/admin/,一般不必再写静态路由):from django.urls import include, path urlpatterns = [ path("base/api/system/", include("django_base_ai.system.urls")), # 管理端:默认 ADMINWEB_AUTO_MOUNT=True,无需再写 path("admin/", ...) ]
- 初始化:执行迁移,并可通过
django_base_ai.dispatch及 system fixtures 初始化菜单、角色、字典等。 - 打开管理端:
python manage.py runserver 0.0.0.0:8000后访问http://127.0.0.1:8000/admin/。
项目结构(简要)
目录与消费边界见 AGENT.md。
DjangoBaseAi/
├── django_base_ai/ # 底座主包(供其他项目安装引用)
│ ├── adminweb/ # 前端产物:index.html、static/(不进 Git)
│ ├── spa/ # 把 adminweb 挂到 /admin/
│ ├── dispatch.py # 系统配置/字典调度入口
│ ├── settings.py # 默认配置(含 ADMINWEB_* )
│ ├── system/ # 唯一应用:底座核心 + ready() 里挂管理端
│ ├── utils/
│ ├── websocket/
│ └── templates/
├── agent/quality/ # 质量报告 JSON,不是文档
├── DjangoBaseAi/
├── conf/
├── tests/
├── pyproject.toml
└── README.md
开发约定(与 Rules/python.mdc 一致)
- PEP 8:全包使用小写+下划线命名,
ruff format .与ruff check .通过后再提交。 - 类型与文档:新代码与核心模块使用类型注解与 docstring。
- 测试:使用 pytest,
DJANGO_SETTINGS_MODULE已写在pyproject.toml,在项目根执行pytest即可。
常用命令
ruff format .
ruff check . --fix
pytest
pytest tests/ -v
pip install build && python -m build
多租户(默认关闭)
开关名 BASE_AI_TENANT_ENABLED,默认 False。定义在 django_base_ai/settings.py。宿主 from django_base_ai.settings import * 之后再设为 True 才打开。不设置、或显式 False,行为与现在的单库底座一致。
下面这份是本仓库的完整约定,按代码实现书写。
第三方不打开开关时
pip install django-base-ai 并且不把 BASE_AI_TENANT_ENABLED 设为 True 的应用:
| 项 | 行为 |
|---|---|
| 登录 | POST /base/api/system/login/ 仍是用户名(或邮箱、手机号)+ 密码,可带验证码。请求里多带 tenant_code 会被忽略,不报错 |
| JWT | 不增加 tenant_code / platform 声明 |
| 用户名 | 仍是整库唯一(Users.username 的 unique=True 没改) |
| 数据库 | 仍是 DATABASES["default"] 这一套。新增路由在关闭时每个方法都返回空,不改查询去向 |
| 菜单 | 没有「租户管理」。init_menu.json 里没有这条 |
| 插件 | 仍按 project_code 安装、启用 |
| 缓存键、媒体路径、Celery 消息头、WebSocket 房间名 | 与改前相同。关闭时不会给缓存键加前缀 |
| 中间件 | TenantMiddleware 会自动插到中间件最前面,但关闭时只调用下一层,不解析令牌 |
需要改的代码:没有。migrate 会多一张登记表 base_ai_tenant(空表),并把 Users.last_token 从 varchar(255) 改为文本字段,否则带 tenant_code 的 JWT 写不进去。其余字段和约束不变。关闭开关时登录请求和 JWT 声明仍与原来一致,多带的 tenant_code 仍被忽略。
打开之后的库
不使用 django-tenants(它只支持 PostgreSQL)。不把底座迁到 PostgreSQL。
- MySQL:一个租户一个库。MySQL 里 schema 就是库。建库用
default连接上的账号执行CREATE DATABASE,账号需要建库权限。库名形如ba_t_{租户编码}。 - SQLite(快速开始):一个租户一个文件,目录为
BASE_AI_TENANT_DB_DIR,未设置时是项目下的tenant_dbs/{编码}.sqlite3。
default 是全局库。每个租户另有一条运行时注册的连接,别名 tenant_{编码}。
| 全局库 | 每个租户库 |
|---|---|
租户登记 Tenant:编码、名称、是否启用、库名、创建时间 |
该租户的用户、部门、角色、菜单、文件、消息、配置、日志等现有业务表 |
平台超管(Users.is_superuser,只在全局库登录) |
该租户自己的用户。用户名只在本库唯一,两个租户可以用同一个用户名 |
插件目录 Plugin 与版本 PluginVersion(全局一份) |
插件安装 PluginInstall、钩子订阅,以及插件自己的业务表 |
进程内插件代码可以共用一份。插件读写数据库必须走当前租户连接:建表用 django_base_ai.plugin.schema.ensure_plugin_models(内部是 active_connection())。不要在插件里另开连接去读别的库。
登录
租户用户仍走 POST /base/api/system/login/。打开开关后请求体必须带 tenant_code。顺序是:先在全局库确认该租户存在且 enabled=True,再切到该租户库校验账号。成功后的 access / refresh JWT 带声明 tenant_code。之后的请求只认令牌里的租户,改 X-Tenant-Code 之类的请求头无效。停用的租户不能登录,已发出的令牌也会被拒绝。
平台超管不走这条登录。单独入口:
POST /base/api/system/tenant/platform_login/
只查全局库,账号必须是全局库里的 is_superuser。JWT 带 platform: true,不带 tenant_code。这个身份可以建租户、启用、停用,不能对租户业务接口做写操作(用户、角色、插件安装等 POST/PUT/PATCH/DELETE 会 403,提示不能直接修改租户业务数据)。平台令牌也不会因为请求头切到某个租户库。
全局库里的平台超管可以这样准备(在没有租户上下文时执行,数据落在 default):
python manage.py createsuperuser
或在打开开关后对全局库执行 python manage.py init(此时「租户管理」菜单会写在全局库)。租户库自己的 init 不会写入「租户管理」。
租户管理菜单与接口
菜单在「管理」分组下,和「插件中心」同级。name=TenantManagement,路由 tenant_management,组件 /@/views/setting/tenantManagement/index.vue,标题「租户管理」。只在开关打开时出现在全局库,因此只有平台超管拉全局库菜单时看得到。租户库没有这条菜单。页面在 DjangoBaseAIWeb 另做,本仓库只提供菜单数据和接口。
接口风格与 /base/api/system/plugin/ 相同:成功 {code:2000, msg, data};列表的 data 内再包 {page, limit, total, data}。下面的 JSON 示例是 data 字段,外面还有 code 和 msg。
两种模式都能匿名访问
GET /base/api/system/tenant/status/
{"enabled": false}
登录页用 data.enabled 决定是否显示租户编码输入框。关闭时也返回 200,enabled 为 false,不要求登录。
平台超管,且开关必须打开(Header:Authorization: JWT <access>,令牌来自平台登录)
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /base/api/system/tenant/ |
分页列表。每项含 id、code、name、enabled、db_name、create_datetime、description |
| POST | /base/api/system/tenant/ |
创建 |
| POST | /base/api/system/tenant/{id}/enable/ |
启用 |
| POST | /base/api/system/tenant/{id}/disable/ |
停用。停用后不能登录 |
创建请求体:
{
"code": "acme",
"name": "Acme",
"admin_username": "acme_admin",
"admin_password": "请换成强密码",
"admin_name": "Acme 管理员"
}
code:小写字母开头,只含小写字母、数字、下划线,最长 32。name 必填。admin_username / admin_password / admin_name 可省略;省略时仍会对新库执行 migrate 和 init(fixture 里的 admin)。填写了用户名就必须带密码。创建过程:写全局登记、建库、对该库 migrate、init、按需写入租户管理员。
开关关闭,或令牌不是平台超管:这些管理接口 403。status 除外。
租户登录(打开开关)
POST /base/api/system/login/
{"username": "acme_admin", "password": "请换成强密码", "tenant_code": "acme"}
成功时 data 在原有 access、refresh、userId、name 之外多一个 tenant_code。JWT 里同样有 tenant_code。没带编码、编码不存在或租户已停用:业务失败(code 4000),消息为「请填写租户编码」或「租户不存在或已停用」。
注册、找回密码、授权码登录、4A / 第三方登录在打开开关后同样要带 tenant_code(JSON 或 query),用户落在该租户库。关闭开关时这些入口不要求该字段。
管理命令
python manage.py migrate_default_tenant --code default --name 默认租户
把当前全局库里的业务数据复制到默认租户库(默认编码 default),然后从全局库删掉业务行。平台超管(is_superuser=True)留在全局库,同时会复制进租户库,所以同一个超管可以用租户编码登录,也可以走平台登录。插件目录留在全局库。
开关关闭时这条命令只打印警告,不改任何数据,也不会自动在部署或 migrate 里执行。 编码不合法时命令以错误退出。
已经迁走过(租户库已有用户,且全局库里不再有非超管用户)时会跳过复制,避免把已经清空的全局库再覆盖回租户库。请在日常使用租户之前执行一次。
新租户不要用这条命令,用上面的创建接口(或自行登记后调用同一套建库、迁移、初始化)。
缓存、Celery、文件、WebSocket
只在开关打开时带租户:
- 缓存键在原键前加上
t:{租户编码}:。没有租户上下文时用t:_global:。关闭时键函数原样调用,键名不变。 - 从带租户上下文的进程
delay/apply_async时,消息头写入base_ai_tenant_code。Worker 须加载django_base_ai.system(AppConfig.ready里挂了信号)。关闭时不加这个头。 - 上传相对路径:打开且已绑定租户时为
files/{租户编码}/{md5}{后缀},否则仍是files/{md5}{后缀}。 - WebSocket 房间:打开时为
user_{租户编码}_{用户id}_{设备}。未绑定租户的令牌会被拒绝。关闭时房间名仍是user_{用户id}_{设备}。
产品怎么打开(例如 DocsAI)
安装新版本不会自动变成多租户。产品需要自己:
- 设置
BASE_AI_TENANT_ENABLED = True。 - 对全局库
migrate(多一张base_ai_tenant,并加长Users.last_token)。开关已打开且已经登记过租户时,这次migrate会把未应用的迁移同步到那些已有租户库,避免库还停在varchar(255)。 - 准备全局库平台超管,用平台登录创建第一个租户;或先
migrate_default_tenant把现有单库数据放进默认租户。 - 登录请求增加
tenant_code。每个新租户库在创建时会migrate+init。已有租户库若仍缺迁移,下一次绑定该租户(登录、刷新令牌)会先补迁移再写last_token。 - 队列、上传目录、WebSocket、以及产品自己的独立服务(不经过这套中间件的进程)要带上租户上下文。插件若自己
connect()到固定库,要改成当前连接。
本阶段不做:计费 / 订阅、独立域名、跨租户查询、DocsAI / DocsWebAI 改造、升版本号、发 PyPI、部署。
测试
ENV=quickstart pytest tests/tenant/ -v
ENV=quickstart pytest tests/login/ -v
tests/tenant/ 覆盖:开关关闭时的登录契约、无租户菜单、用户名仍全局唯一、缓存键不变、迁移命令不改数据;开关打开时两个租户同名用户互不可见(改请求头、改令牌载荷都不行)、停用不能登录、A 的插件启用不影响 B、新建租户能初始化并登录、默认租户迁移命令、平台超管能建/停租户但不能改租户业务数据、管理菜单下有租户管理。
已知限制
- 插件目录是全局一份。能调用插件目录接口的租户管理员登记的插件,其它租户也能在目录里看到。安装和启用状态仍按租户库分开。删除目录项不会逐个租户库去卸安装。
- 平台超管令牌不能写租户业务接口,也不能靠请求头进入租户库。
- 一个请求里的跨库操作不是同一个数据库事务。
- Celery 任务如果不是在已绑定租户的进程里发出的,消息头里没有租户,Worker 按全局库执行。
- 缓存键加前缀后更长。原来就把整段 JWT 当缓存键的用法,在 Memcached 250 字符限制下可能告警;关闭开关时键名不变。
token_blacklist、guardian在打开开关且当前是租户请求时跟租户库走,避免登录黑名单的用户外键跨库。其它第三方应用若有指向Users的外键,需要同样跟着当前租户库,或不要建数据库级外键。
插件中心
把独立插件工程打成 zip,在管理端登记后安装、启用。进程内插件不必写入宿主 INSTALLED_APPS。示例工程同级仓库 PluginDemo/。
侧栏:管理 → 插件中心(PluginCenter / plugin_center)。DjangoBaseAIWeb 另有配置路由 /setting/pluginCenter。
参与方与形态
| 角色 | 作用 |
|---|---|
| 插件工程 | plugin.json + Python 包 + 可选 Vue frontend/dist,pack.sh 产出 zip |
| 宿主底座 | 目录、解压、importlib、建表、挂 /plugins/ |
| 管理端 | 上传 / 安装 / 启用;iframe 打开插件 UI |
| 运行时目录 | {BASE_DIR}/plugin_workspace/(zip 与解压结果,勿提交 git) |
| kind | 加载 | 路由 | 用途 |
|---|---|---|---|
inproc |
zip 解压后加载 entry |
/plugins/{url_prefix}/ |
进程内 API + 静态 UI |
remote |
关联 Apps + 钩子,不进进程 |
不挂宿主路由 | 独立 HTTP 服务 |
安装包结构(inproc)
bohe.demo-1.1.0.zip
├── plugin.json # 必填:code / name / version / kind;inproc 还须 entry
├── backend/<pkg>/ # entry = 模块路径:类名
└── frontend/dist/ # 可选;启用后托管为 /plugins/{prefix}/ui/
Vue 的 base 须为 /plugins/{url_prefix}/ui/。requires 必须是宿主 BASE_AI_HOST_CAPABILITIES ∪ 底座 BASE_CAPABILITIES 的子集,否则无法启用。menus / permissions 目前只入库,不自动写侧栏/RBAC。
生命周期
上传登记 → 安装(install) → 启用(enable) → 停用(disable) → 卸载(uninstall)
| 动作 | 接口 | 宿主行为 |
|---|---|---|
| 登记 | POST /base/api/system/plugin/upload/ |
zip 或 package_uri;校验清单;写入 Plugin + PluginVersion |
| 目录 | GET …/plugin/catalog/ |
目录 + 本项目安装态 |
| 项目信息 | GET …/plugin/project_info/ |
project_code + 宿主能力 |
| 安装 | POST …/plugin/{id}/install/ |
兼容性与 requires;PluginInstall;get_models() 建表;install();同步 hooks |
| 启用 | POST …/plugin/{id}/enable/ |
未安装则先装;enable();PluginRegistry.reload() |
| 停用 | POST …/plugin/{id}/disable/ |
disable();卸路由;保留安装记录与业务表 |
| 卸载 | POST …/plugin/{id}/uninstall/ |
uninstall();删安装与 hooks;默认不 DROP 表 |
启用后典型 URL(以 PluginDemo、url_prefix=demo 为例):
| URL | 说明 |
|---|---|
/plugins/demo/ping/ 等 |
插件 get_urls() |
/plugins/demo/ui/ |
托管 frontend/dist |
| 管理端「打开界面」 | iframe → 上述 UI |
开发代理:DjangoBaseAIWeb(如 :5789)已转发 /plugins 到底座(如 :8075)。
插件表约定
插件不进 INSTALLED_APPS,不能对插件包 makemigrations。模型经 BasePlugin.get_models() 在 install 时由宿主 schema_editor 建表:Meta.app_label="system"、managed=False、独立 db_table。卸载默认保留数据。
安全
package_uri仅允许BASE_AI_PLUGIN_WORKSPACE或BASE_AI_PLUGIN_ALLOWED_PACKAGE_DIRS- 登记写
checksum(sha256),加载前校验 - zip 大小/成员数限制,拒绝 zip-slip
- 多 worker:启停会 bump registry 代际,下次访问
/plugins/热加载;只装可信包
多租户
BASE_AI_TENANT_ENABLED 关闭时:安装/启用按 project_code,与单库一致。
打开后:目录与版本在全局库;安装/启用在当前租户库。A 租户启用不影响 B。进程内代码可共用,建表与查询须走当前租户连接(ensure_plugin_models / active_connection()),不要自连固定库。
快速验收(PluginDemo)
cd PluginDemo && ./pack.sh
# 管理端 → 管理 → 插件中心 → 上传 dist/bohe.demo-*.zip → 安装并启用 → 打开界面
curl -s -H "Authorization: JWT <TOKEN>" \
http://127.0.0.1:8075/plugins/demo/ping/
OAuth2 第三方接入(Authorization Code)
本平台作为统一登录门户。第三方在管理端 应用管理 注册后,用标准 Authorization Code 拿用户信息。演示工程:test/oauth_demo_fastapi/。
与「个人中心授权码」的区别(必读)
OAuth2 code |
个人中心 ac_code |
|
|---|---|---|
| 用途 | 第三方网站 / 应用登录或授权绑定 | 用户本人在个人中心生成的长期授权码换 JWT |
| 存储 | 仅缓存 oauth:code:,5 分钟、一次性 |
落库 Users.authorization_code(AES-GCM) |
| 入口 | /#/oauth/authorize → oauth/token/ → oauth/userinfo/ |
user/get_ac_code/ → user/ac_code_to_login/ |
| 能否混用 | 禁止:个人中心码不能当 OAuth code 换票 |
与 OAuth 无关 |
1. 注册应用(管理端 → 应用管理)
| 字段 | 说明 |
|---|---|
appid(Apps.agent_id) |
自动生成唯一 8 位数字;对外 query/body 优先用 appid(兼容 client_id) |
密钥(secret) |
自动生成;换票时作 client_secret |
OAuth 认证模式(oauth_auth_mode) |
0 授权绑定(默认):同意页须用户点「允许」,且 API 须 consent=true;1 SSO 登录:登录成功后跳过同意页直接发码回跳 |
IP/域名白名单(server_ip) |
多行混填;redirect_uri 的 host(域名或 IP)必须命中;换票时若配置了 IP 条目则校验来源 IP |
OAuth 回调地址(oauth_redirect_uris) |
多行绝对 URL;若配置则须精确匹配整行,同时 host 仍须可信 |
白名单全空则拒绝一切 redirect_uri。生产建议同时配置精确回调与白名单。
2. 浏览器授权入口(前端统一登录页)
认证只走系统登录页 /#/login(勿另写登录页)。授权入口:
GET {WEB}/#/oauth/authorize?response_type=code&appid={appid}&redirect_uri={urlencoded}&state={random}
未登录 → 跳转 /#/login 并透传 appid / redirect_uri / state;登录成功回到授权页。
授权绑定(mode=0)
- 同意页展示:应用名称、将授权权限、当前账号
- 用户点 允许 →
POST /base/api/system/oauth/authorize/(body 含consent: true)→ 为当前用户 upsert「授权-{应用名称}」个人信息授权码(同appid仅一条)→ 回跳{redirect_uri}?code=...&state=... - 取消 →
{redirect_uri}?error=access_denied&state=...
SSO 登录(mode=1)
已登录且 redirect_uri 合法 → 不弹同意页,自动发码并回跳。后端不要求 consent。
成功发码会写 登录日志(login_type=5 OAuth授权,字段 appid)。
3. 换票与用户信息
POST /base/api/system/oauth/token/
Content-Type: application/json
{
"grant_type": "authorization_code",
"code": "...",
"appid": "{appid}",
"client_secret": "{secret}",
"redirect_uri": "https://app.partner.com/oauth/callback"
}
{ "code": 2000, "data": { "access_token": "...", "token_type": "Bearer", "expires_in": 1800 } }
GET /base/api/system/oauth/userinfo/
Authorization: Bearer {access_token}
返回 id / username / name / email / 部门与角色摘要。
公开元数据(不含密钥):
GET /base/api/system/oauth/client_meta/?appid={appid}&redirect_uri={optional}
4. 安全要点
- 授权绑定发码:后端强制
consent=true,不能只靠前端隐藏同意页绕过 redirect_uri:校验 host∈可信 IP/域名;有精确列表时还须整 URL 匹配code:缓存、5 分钟、一次性;与个人中心授权码隔离- 登录认证 UI:仅
Login.vue;/oauth/authorize只做同意/自动回跳,不是第二套登录页 - 建议生产:强制非空
oauth_redirect_uris;后续可补 PKCE / state 服务端绑定
5. 多租户下的 OAuth
开关打开后,浏览器登录与发码落在当前租户库的用户/应用数据上;Apps、登录日志均在租户库。平台超管令牌不能代替租户用户完成授权绑定。第三方接入方仍使用同一套 oauth/* 路径,由平台 JWT 的 tenant_code 决定库。
6. 验收演示
# 需已启动底座 API(如 :8075)与管理端(如 :5789)
cd test/oauth_demo_fastapi # 相对 BoheServer 仓库
.venv/bin/python e2e_accept.py
# 浏览器:http://127.0.0.1:8765/
# 「获取授权码」→ appid=87654321(同意页)
# 「OAuth2登录」→ appid=87654322(跳过同意)
个人中心授权码(ac_code)
用于当前登录用户生成/重置授权码,供自有脚本或受信任客户端换 JWT;不是 OAuth2 门户的第三方 Authorization Code。
开关
- 系统配置
third.enable_ac_code_login,或 settingsENABLE_AC_CODE_LOGIN - 关闭时
ac_code_to_login返回未启用
接口
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /base/api/system/user/get_ac_code/ |
JWT | 获取或补发本人授权码 |
| GET | /base/api/system/user/reset_ac_code/ |
JWT | 重置授权码 |
| POST | /base/api/system/user/ac_code_to_login/ |
匿名(限流) | body:{ "ac_code": "..." };多租户开启时另带 tenant_code |
换发的 JWT 带声明 ac_login,不写 last_token,避免挤掉浏览器会话。成功写登录日志 login_type=4。
接入示例
POST /base/api/system/user/ac_code_to_login/
Content-Type: application/json
{ "ac_code": "<从个人中心复制的授权码>" }
多租户:
{ "ac_code": "...", "tenant_code": "acme" }
第三方接入方式对照
| 场景 | 推荐方式 | 说明 |
|---|---|---|
| 扩展底座能力(进程内 API + UI) | 插件中心 inproc zip | 见插件中心;不必改宿主 INSTALLED_APPS |
| 独立 HTTP 服务挂到平台 | 插件中心 remote + 应用管理 | 钩子回调 / OpenAPI ticket,不挂 /plugins/ |
| 外部 Web/App 用本平台账号登录 | OAuth2,应用模式 SSO 登录 | 跳过同意页,登录后直接回跳 |
| 外部应用要读用户资料且需用户知情 | OAuth2,应用模式 授权绑定 | 同意页展示权限,须手动允许 |
| 自有工具 / 脚本代替密码登录 | 个人中心 ac_code | 勿走 OAuth authorize |
| 企业 4A / 统一认证回跳 | sign_login/ 或登录页 accToken/ticket |
系统配置 SSOLOGIN.* / third.login_type |
| 多租户产品 | 打开 BASE_AI_TENANT_ENABLED |
登录与上述换票均带 tenant_code;见多租户 |
许可证
见仓库根目录 LICENSE。
Metadata
Release files for django-base-ai 1.0.140
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_base_ai-1.0.140.tar.gz | 9.4 MB | Without provenance | Details for django_base_ai-1.0.140.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_base_ai-1.0.140-py3-none-any.whl | Python 3 | none | any | Details for django_base_ai-1.0.140-py3-none-any.whl |
Total release size: 19.1 MB
Release files / django_base_ai-1.0.140.tar.gz
| Download URL | django_base_ai-1.0.140.tar.gz |
|---|---|
| Size | 9.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4c18885506cd0841c4435ab311170a4a435c774e4a86b54dea3bd14a7dbbf84
|
|
BLAKE2b-256 checksum How to use checksums |
eb7fca45d2e6d149dcb9d01338c794d6d712efda583382e4997ca126bc9f56ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.6
|
Release files / django_base_ai-1.0.140-py3-none-any.whl
| Download URL | django_base_ai-1.0.140-py3-none-any.whl |
|---|---|
| Size | 9.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d4f69ad647590cc27e29ee8f158cb0d9ce3e464c32d5d1549c51d875bc10b30
|
|
BLAKE2b-256 checksum How to use checksums |
afdcdc6fc630d80ad1146a6b4d2a208605c79cf0a52da27f93f88adda5ee2353
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.6
|
Security for django-base-ai 1.0.140
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.