xadmin-基于Django+vue3的rbac权限管理系统
版本 5.0.1：变更总览见 CHANGELOG.md；4.x → 5.0 升级步骤见 docs/ops/upgrade-5.0.md（迁移链收敛为初始迁移 +
upgrade_ledger账本认领，4.2.5 起可原地升级，更早的库走清库重建）。 前后端必须同版本发布（CI 三方校验server/const.py↔xadmin-client/package.json↔ 发布 tag）。
https://xadmin.dvcloud.xin/
账号密码：admin/admin123（线上演示账号；本地初始化的账号为 xadmin，见下方快速开始）
# 方式一：Docker 一键体验（起后端全栈 + 幂等初始化 + 启动前端；需 Docker 与 Node/pnpm）
bash ops/dev_up.sh # --with-demo 追加演示数据；--backend-only 仅起后端；--hot 热加载（改后端代码自动重载）；--help 查看帮助- 浏览器打开 http://127.0.0.1:8848，账号
xadmin，初始密码在初始化输出中仅打印一次； - 停止后端：
bash ops/dev_down.sh；重复执行是幂等的（升级后同样适用）； - 首次运行会自动构建镜像（数分钟）。
# 方式二：本机源码启动（Python 3.14+，需自备数据库（PostgreSQL/MySQL/SQLite）与 Redis）
uv sync --all-groups # 依赖以 uv.lock 为准，见下方「依赖管理」
# 无 uv 时：python3.14 -m venv .venv && source .venv/bin/activate
# && pip install -r requirements.txt -r requirements-dev.txt
cp config_example.yml config.yml # 可跳过：不创建时自动使用内置默认配置并自动生成 SECRET_KEY
uv run python manage.py migrate # 走 uv 时命令加 `uv run`；或 source .venv/bin/activate 后直接用 python
uv run python ops/init_data.py # 幂等；--with-demo / --skip-ip-db / --admin-password
uv run python manage.py start all -d超管初始密码：--admin-password 或环境变量 XADMIN_ADMIN_PASSWORD 显式指定，未设置时随机生成并仅打印一次。
- 事实源：根
pyproject.toml（运行依赖 +dev组）与uv.lock（锁文件，入库）； 框架内核（common）是工作区成员——打包元数据在packages/xadmin-common/pyproject.toml， 源码在packages/xadmin-common/common/，根项目以workspace + editable消费（改内核源码即时生效）； 分发名xadmin-common，独立构建uv build --package xadmin-common，宿主接线与 settings 契约见 docs/architecture/kernel-package.md； - 安装路径（
uv.lock是版本唯一依据）：本地开发uv sync --all-groups；CIuv sync --locked+uv lock --check（见.github/workflows/）；容器构建uv pip install -r requirements*.txt --index-url ${PIP_MIRROR}（见Dockerfile-base/Dockerfile-dev）。容器为何不用uv sync --frozen：--frozen不重新解析，uv 会直接用uv.lock里固化的files.pythonhosted.org（PyPI 官方 CDN）地址下载，绕过 PIP_MIRROR （astral-sh/uv#19625）——国内直连官方 CDN 只有 10 KB/s 级、走镜像源可达 10+ MB/s。这也是requirements*.txt的第一个硬用途：镜像源场景的 安装输入（与uv.lock的一致性由tests/unit/test_dependency_manifest.py守护）； requirements.txt/requirements-dev.txt是uv export的导出产物（请勿手工编辑， 改依赖 = 改 pyproject 后重新导出）。它们不再是安装依据，保留给三类固定用途：pip 生态安全扫描 （pip-audit -r requirements.txt）、无 uv 环境的手工与离线安装、国产化平台版本适配 （见docs/ops/deployment.md§7）；- uv 版本下界：
[tool.uv].required-version（CI 的astral-sh/setup-uv依此选版本； 容器内由ARG UV_VERSION固定，两处同源）：
uv sync --all-groups # 创建/同步 .venv（含 dev 组；内核以 editable 安装）
uv lock # 变更依赖（含内核成员 pyproject）后刷新 uv.lock（入库，保证解析可复现）
# 重新导出产物（pyproject.toml 头部注释同口径）：
uv export --no-hashes --no-emit-project --no-emit-workspace --no-group dev --no-annotate -o requirements.txt
uv export --no-hashes --no-emit-project --no-emit-workspace --only-group dev --no-annotate -o requirements-dev.txt- 可选依赖（对象存储后端）：声明于两处
[project.optional-dependencies].storage（根项目与内核 成员同口径），默认不装，未装时文件链路回退本地，启用方式uv sync --extra storage或pip install django-storages boto3（详见docs/ops/storage.md）； - 守护（
tests/unit/test_dependency_manifest.py，纯解析、不依赖网络）：pyproject ↔ 产物 ↔ uv.lock 三方一致（工作区成员以路径形态存在、经--no-emit-workspace从产物剔除）、工作区骨架 （成员 editable 锁定 / wheel 只收内核包本体 / 内核依赖全部落在运行产物中）、容器与 CI 的安装方式 未回退到产物、uv 版本同源、.dockerignore排除宿主环境；本机存在 uv 时额外校验「产物与导出逐行一致」。
优先查阅本仓库文档中心：docs/README.md（环境搭建、架构总览、三层权限、部署运维 runbook、ADR）
- 本地部署 / Docker 部署 / 升级回滚 / 国产化适配：docs/ops/deployment.md
- 常见故障排查：docs/ops/runbook.md
- 外站在线文档（补充资料）：https://docs.dvcloud.xin/
python manage.py start all -d # -d 参数是后台运行，如果去掉，则前台运行日常运行推荐直接用上面的 A 一键命令；以下为拆解示意，各服务参数（端口 / 地址 / 认证）以
packages/xadmin-common/common/management/commands/services/下的定义为准。
python manage.py runserver 0.0.0.0:8896python -m celery -A server beat -l INFO --scheduler django_celery_beat.schedulers:DatabaseScheduler --max-interval 60
python -m celery -A server worker -P threads -l INFO -c 10 -Q celery --heartbeat-interval 10 -n celery@%h --without-minglepython -m celery -A server flower -logging=info --url_prefix=api/flower --auto_refresh=False地址与端口由
config.yml的CELERY_FLOWER_HOST/CELERY_FLOWER_PORT决定（未配置认证时仅允许绑定 127.0.0.1，见packages/xadmin-common/common/management/commands/services/services/flower.py）。
## 捐赠
如果你觉得这个项目帮助到了你，可以 [star](https://github.com/nineaiyu/xadmin-server) 表示鼓励；捐赠方式与捐赠者权益见[捐赠页](https://docs.dvcloud.xin/donate.html)。