mirror of https://github.com/fastapiadmin/FastapiAdmin.git synced 2026-10-14 05:00:10 +00:00

T

zhangtao 644d262cad refactor(backend): 错误码收敛为单一事实来源，统一异常写法

错误码（t16）
- HTTP 语义只由 core/exceptions.py 的 RET.code → fastapi.status 映射决定；
  映射表显式登记 -1→400 与全部「数值即 HTTP 状态」的 RET 成员，_DEFAULT_BUSINESS_STATUS
  降为「新增码忘登记」的安全网
- 移除冗余 status_code：131 处调用点改为纯 code 表达；security.py/dependencies.py
  的 status_code=401/403 去除（映射表已给）；get_or_404 → code=RET.NOT_FOUND.code
- 新增静态护栏（AST）：app/ 下除 exceptions.py 外不得出现 status_code 传参，
  路由装饰器 201 白名单显式放行并断言白名单非空

异常写法统一（t19）
- 删除 CustomException.internal 及 132 处包装：意外异常直接冒泡，由全局
  @app.exception_handler(Exception) 统一映射 5xx + 通用文案 + 日志；
  需要运维上下文处改为 logger.exception("<业务动作>失败") + raise
- 构造器不再接受 status_code 参数（属性保留，由 code 派生）→ 结构上杜绝第二来源
- 修复 6 处「宽泛 except 把 400 包成 500」的语义反转（补 except CustomException: raise），
  并加 AST 护栏防止回潮
- 全局 SQLAlchemyError：非完整性错误由 400 改为 503（连接类）/500（其它），
  不再把驱动原文/异常类型拼进客户端 msg；顺带修掉不存在的
  status.HTTP_403_SERVICE_UNAVAILABLE 常量（命中即 AttributeError→500）

验证：pytest 97 passed / ruff 全绿；AST 审计残留 0；护栏红绿测试通过；
线上实测验证码过期仍 400 并保留业务文案、无令牌 401。

2026-10-04 05:44:21 +08:00

.github/workflows

chore(deploy): 成品部署链路、依赖分组与运维基建

2026-10-04 04:26:03 +08:00

backend

refactor(backend): 错误码收敛为单一事实来源，统一异常写法

2026-10-04 05:44:21 +08:00

docker

chore(deploy): 健康检查发正确 Host、list 型配置改 JSON、Host 校验收窄

2026-10-04 05:12:37 +08:00

frontend

fix(frontend): 修复 5 条 P0（生产构建开关、令牌刷新、上传路径、WS 与开发地址）

2026-10-04 04:33:42 +08:00

.dockerignore

chore(deploy): 成品部署链路、依赖分组与运维基建

2026-10-04 04:26:03 +08:00

.gitignore

chore(deploy): 成品部署链路、依赖分组与运维基建

2026-10-04 04:26:03 +08:00

AUDIT-REPORT.md

chore(deploy): 健康检查发正确 Host、list 型配置改 JSON、Host 校验收窄

2026-10-04 05:12:37 +08:00

CHANGELOG.md

docs: 更新贡献指南，补充小程序开发说明

2026-09-06 21:19:58 +08:00

CONTRIBUTING.md

docs: 更新贡献指南，补充小程序开发说明

2026-09-06 21:19:58 +08:00

deploy-artifacts.sh

chore(deploy): 成品部署链路、依赖分组与运维基建

2026-10-04 04:26:03 +08:00

deploy.sh

chore(docker): 调整 dockerignore 排除上传目录

2026-09-07 01:38:38 +08:00

DEPLOYMENT.md

chore(deploy): 健康检查发正确 Host、list 型配置改 JSON、Host 校验收窄

2026-10-04 05:12:37 +08:00

LICENSE

chore: 更新项目所有者信息为fastapiadmin

2026-01-18 03:35:38 +08:00

README.en.md

docs(readme): 更新项目说明与界面截图

2026-09-06 20:52:11 +08:00

README.md

docs(readme): 更新项目说明与界面截图

2026-09-06 20:52:11 +08:00

REQUIREMENTS.md

docs: add SaaS multi-tenant platform requirements

2026-09-06 21:19:50 +08:00

SKILL.md

refactor(router): simplify route cache logic, remove nested parent component

2026-09-14 01:06:20 +08:00

README.en.md

FastApiAdmin ^v3.0.0

🚀 Exceptional Code Quality, Production-Ready Admin Dashboard in 5 Minutes

Full-stack rapid development platform powered by FastAPI + Vue3 + TypeScript. Web, H5, and Mini Program — all in one project.

English | 简体中文

🖥️ Screenshots

Web

Mobile (H5 / Mini Program / App from one codebase)

💡 Why FastapiAdmin?

You Need	FastapiAdmin	Django Admin	Frontend-Only
🎯 Ready-to-use admin system	✅	⚠️ Limited	❌ UI only
⚡ FastAPI async high-performance backend	✅	❌ Sync-first	❌ No backend
🔐 RBAC menu/button/data level permissions	✅	❌ Basic	❌
🤖 Code generator (table → full CRUD)	✅	❌	❌
📱 Mobile (H5 + Mini Program) included	✅	❌	❌
🐳 Docker one-click deploy (Nginx + SSL)	✅	❌	❌

👉 Full comparison: Why FastapiAdmin?

🍪 Live Demo

	URL	Account
💻 Web	service.fastapiadmin.com/web	`admin` / `123456`
📱 Mobile	service.fastapiadmin.com/app	`admin` / `123456`
📖 Official Docs	service.fastapiadmin.com	No login

🚀 5-Minute Quick Start

# 1. Clone
git clone https://github.com/fastapiadmin/FastapiAdmin.git

# 2. Configure environments
cp backend/env/.env.example backend/env/.env.dev
cp frontend/web/.env.development.example frontend/web/.env.development

# 3. Start backend (auto-creates tables + seed data on first run)
cd backend && uv sync && uv run main.py run --env=dev

# 4. Start frontend
cd ../frontend/web && pnpm install && pnpm run dev

# ✅ Open http://127.0.0.1:5173, login with admin/123456

Requirements
Python ≥ 3.12	Node.js ≥ 20 + pnpm
MySQL 8.0+ / PostgreSQL 14+	Redis 6.x / 7.x

🐳 Or: One-Command Docker Deployment

cp docker/.env.example docker/.env    # Fill in MySQL / Redis passwords
./deploy.sh                           # Build images and start the full stack (Nginx + SSL included)

For ports, SSL certificates and frontend builds, see the Docker deployment guide.

📦 Structure

FastapiAdmin/            # Monorepo full-stack project
├─ backend/              # FastAPI backend (Pydantic 2.0 + SQLAlchemy + Alembic)
├─ frontend/
│   ├── web/             # Vue3 Web (Element Plus + TypeScript)
│   ├── app/             # UniApp Mobile (H5 + Mini Program + App)
│   └── docs/            # VitePress documentation
├─ docker/               # Docker Compose deploy (Nginx + SSL)
├─ deploy.sh             # One-click deploy script
└─ LICENSE               # MIT

📌 Built-in Features

200+ REST endpoints · MySQL / PostgreSQL / SQLite · SFTP / S3 / OSS / COS / OBS storage adapters · Trim modules with a single ENABLED_MODULES entry

Core Modules (always enabled, cannot be removed)

Module	Capabilities
📊 Dashboard	Workbench, Analytics
⚙️ System Management	Users, Roles, Menus, Departments, Positions, Dicts, Config, Notices, Tickets, Versions
👀 Monitoring	Online users, Server monitoring, Cache monitoring
📝 Logs	Operation audit
🧰 Dev Tools	API Docs

Extension Modules (enabled by default, trim via `ENABLED_MODULES`)

Module	Capabilities	Toggle
🧩 Task Management	Scheduled tasks + visual workflow orchestration (built-in business nodes)	`task`
🔧 Code Generator	Table → full frontend/backend code	`generator`
📁 Storage	Unified file / object storage (SFTP / S3 / OSS / COS / OBS)	`storage`
🤖 AI Chat	Agno-powered agent conversations	`ai`
💬 Internal Chat	Text-only private / group chat between users (WebSocket real-time push + unread badge)	`chat`

🔧 Module Toggling

Extension modules can be enabled/disabled on demand via ENABLED_MODULES in backend/app/config/setting.py — just remove an item from the list; no code or menu deletion needed. The corresponding REST endpoints, WebSocket endpoints and initialization logic will not be loaded automatically:

# e.g. Disable internal chat and AI assistant, keep the rest
ENABLED_MODULES = ["generator", "task", "storage"]

🚦 Deployment Notes

Chat scope: Internal chat is positioned as lightweight internal communication — text-only messages. No file transfer, recall, read receipts, or multi-device sync (IM features). For strong IM needs, integrate mature products such as WeCom / DingTalk / Feishu. It can be disabled anytime by removing chat from ENABLED_MODULES.
Single-instance deployment: Real-time features (internal chat WebSocket, scheduled task scheduler) rely on in-memory connections and local scheduling within a single instance — please deploy as a single instance. For horizontal scaling, integrate Redis Pub/Sub or a message queue yourself.
Key security: Configure all third-party keys (AI, cloud storage, etc.) in the backend/env/.env.* environment variables. Never commit them to the repository or store them in the database.
Database migrations: Manage schema changes with Alembic migrations in production (uv run alembic upgrade head); create_all is only a fallback for first-time initialization.