Skip to main content

DjangoBaseAi

Django 通用底座:在 Django + DRF 之上提供企业级底座(认证、RBAC、组织架构、操作/登录日志、文件与消息等),以及可选 AI 工作台 / IM。产品业务(对话、文档、PPT 等)放在消费方仓库,不要写进本包。

给 AI / 后续模块开发:先读 AGENT.md。

  • 包名:django-base-ai(导入名:django_base_ai)
  • 快速开始(pip 安装 + 配置步骤,无需 MySQL/Redis):help/QUICKSTART.md
  • 架构说明:help/ARCHITECTURE.md — 底座分层、AI 与扩展、集成方式
  • 代码逻辑图:help/code-map/README.md — 总览、登录鉴权、RBAC、存储、扩展点

快速开始(首次使用)

使用 pip 安装,在新建或已有 Django 项目中按文档配置即可,无需克隆仓库、无需 MySQL/Redis(SQLite + 内存缓存)。

pip install django-base-ai
django-admin startproject myproject && cd myproject

然后在项目的 settings.py 中先 from django_base_ai.settings import *,再按 help/QUICKSTART.md 配置数据库(SQLite)、缓存(内存)、INSTALLED_APPS、MIDDLEWARE、路由等;执行 migrate、runserver 即可访问。建议再执行 python manage.py init 初始化菜单/角色/字典。对话与 PPT HTTP 接口在产品仓库,不在本包。

发布时前端:在本仓执行 ./build.sh 会自动在同级 ../DjangoBaseAiWeb(或本仓 ./web)跑 npm run build:pack,再拷入 django_base_ai/static/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/static/adminweb/index.html True:自动挂到根 URLconf;False:不挂,需自行 include
ADMINWEB_MOUNT_PATH "/admin/" 仅在自动挂载开启时生效 浏览器访问前缀;/admin 会 302 到带尾斜杠的路径
包内 static/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 工作台 ai_desk_app_manage/ 与菜单权限打通(对话/PPT HTTP 在产品仓库)

配置 AI 供应商(见 conf/env.py 或文档)后即可使用,无需改业务代码。

底座核心(通用能力,支撑 AI 与业务)

模块 说明
认证 JWT(SimpleJWT)、单点/第三方登录、验证码、登出、Token 刷新
RBAC 用户、角色、部门、菜单、按钮权限、接口白名单、数据权限过滤
系统配置 字典、系统配置键值、调度中心(dispatch)、初始化接口
审计与日志 操作日志、登录日志、日志文件分析/下载/实时 tail
文件与存储 文件夹、文件上传/列表/下载、导入导出(Excel)
消息与协作 消息中心、常用联系人、协作人、我的上级、WebSocket
任务与配置 基础任务、任务历史、应用/标签、数据可视化配置
工具 统一 JSON 响应、分页、异常处理、权限校验、加解密、节假日、健康检查等

其他扩展(按需使用)

模块 说明
IM 会话、单聊、群聊、问题分组、问答、聊天记录
数据分析 通用分析视图(base_analyze)

统一响应格式

除流式接口与 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/ 用户名密码登录(可选验证码) { code, msg, data: { access, refresh, name, userId, avatar, user_type, skin, pwd_defaulted, user_config, is_staff, dept_info?, role_info? } }
POST sign_login/ 单点登录/第三方集成 同上结构
POST custome_login/ 自定义登录 同上结构
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/ 应用管理
tags/ 标签
collaborator/ 协作人
my_superiors/ 我的上级
ai_desk_app_manage/ AI 工作台应用管理
im_session/ IM 会话
im_chat_to_user/ IM 单聊
im_chat_question_group/ IM 问题分组
im_chat_question/ IM 问题
im_chat_to_group/ IM 群聊
im_chat_to_group_message/ IM 群消息
im_chat_qa/ IM 问答
im_chat_record_form/ IM 聊天记录表单
login_log/ 登录日志
base_analyze/ 数据分析(ViewSet,多为 GET 自定义 action)

对话 / PPT HTTP 路由不在本包,见消费方(如 DocsAI AIChat)。本包提供 django_base_ai.utils.ai 客户端与 ai_desk_app_manage/。


其他资源上的自定义 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,再按 help/QUICKSTART.md 在项目中完成配置即可。

Windows / Linux 兼容:uwsgi、supervisor 为 Linux/macOS 生产部署工具,包内代码不依赖它们。pip 会根据 sys_platform 自动跳过 Windows 上的这两项(无需 --no-deps);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。

本地一键启动(对接 DjangoBaseAiWeb)

需同级存在前端仓库 DjangoBaseAiWeb(已 pnpm install)。

# 后端(:8075) + 前端 Vite(:5789)
./dev_run.sh

# 仅后端 / 仅前端
./dev_run.sh api
./dev_run.sh web

# 后端用 SQLite 快速开始(无需 MySQL/Redis)
ENV=quickstart ./dev_run.sh

访问:http://localhost:5789/。可用 FRONTEND_DIR / BACKEND_PORT / WEB_PORT 覆盖路径与端口。


在项目中使用(一键集成)

安装 DjangoBaseAi 后,按以下步骤即可将 AI 能力与底座(RBAC、组织架构与基础能力) 一键集成到现有 Django 项目。

  1. 安装:将本仓库可编辑安装或打包后安装到目标 Django 项目环境。
  2. 配置:在目标项目 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、文本润色等接口。
  3. 路由:在目标项目 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/", ...)
    ]
    
  4. 初始化:执行迁移,并可通过 django_base_ai.dispatch 及 system fixtures 初始化菜单、角色、字典等。
  5. 打开管理端:python manage.py runserver 0.0.0.0:8000 后访问 http://127.0.0.1:8000/admin/。

项目结构(简要)

目录、消费边界与 Git / PyPI 版本差见 PROJECT_STRUCTURE.md。分层说明见 help/ARCHITECTURE.md。

DjangoBaseAi/
├── django_base_ai/          # 底座主包(供其他项目安装引用)
│   ├── adminweb/            # /admin/ 零配置托管(自动挂载包内 SPA)
│   ├── dispatch.py          # 系统配置/字典调度入口
│   ├── settings.py          # 默认配置(含 ADMINWEB_* )
│   ├── system/              # 唯一应用:底座核心 + ready() 里挂管理端
│   ├── static/adminweb/     # 发布时打进 wheel 的前端产物(不进 Git)
│   ├── utils/
│   ├── websocket/
│   └── templates/
├── help/
├── 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

许可证

见仓库根目录 LICENSE。

Metadata

Release files for django-base-ai 1.0.129

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-base-ai 1.0.129
File Size Uploaded Provenance Actions
django_base_ai-1.0.129.tar.gz 9.4 MB Without provenance Details for django_base_ai-1.0.129.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-base-ai 1.0.129
File Interpreter ABI Platform Actions
django_base_ai-1.0.129-py3-none-any.whl Python 3 none any Details for django_base_ai-1.0.129-py3-none-any.whl

Total release size: 19.2 MB

Release files / django_base_ai-1.0.129.tar.gz

Download URL django_base_ai-1.0.129.tar.gz
Size 9.4 MB
Tags Source
SHA-256 checksum
How to use checksums
d227482b6c8b90b8e90b3fcd8c5b8808e6a7c0e50027fd39da476066746b0060
BLAKE2b-256 checksum
How to use checksums
0fa94e797583baf1ec0ae33e75e9f11d4a3901305535ab3f6c27cf52269c0bd9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Release files / django_base_ai-1.0.129-py3-none-any.whl

Download URL django_base_ai-1.0.129-py3-none-any.whl
Size 9.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f552f9714a25eec41ddcbca27b766f51b187b0fae3c2aa7aedde8f36d4676ad2
BLAKE2b-256 checksum
How to use checksums
9c17fba6ab7dd4f95353ab16cf8d514323a9f5d80a8d67059ba246521bbcfecc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.4

Security for django-base-ai 1.0.129

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.

Release history Release notifications | RSS feed

This release

1.0.129 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page