Pro React Admin

供团队复用的 React 管理后台脚手架。安全项目预设提供受保护路由、租户身份、服务端授权、持久化资源与审计；展示应用、双构建器、微前端示例和独立 UI 包可按需选用。基于 React 19、Ant Design 6、React Router 7、Zustand 5 和 TypeScript 6。

第一次使用建议从下方的安全项目预设开始。线上项目概览和工程导览展示源码、验证命令与交付边界；公开站点使用浏览器演示数据。

要直接体验类似 Ant Design Pro 的常见管理页，登录后打开“业务页面模板”：查询表格、基础表单、分步表单、详情和提交结果在默认应用与 Enterprise 入口均可运行。按业务页面模板指南可从页面走到源码、数据 Provider、权限策略和验证命令。模板记录只属于当前工作区会话。

线上预览

Pages 的新增示例和全部应用入口以本次 Actions 部署成功为准。第一次发布可按GitHub Pages 与 Vercel 部署实操完成构建与验收；手动触发、本地上传、Release 和回退见手动部署指南。Pages 配置见GitHub 部署指南，组件预览见Storybook 指南。

快速上手

要求 Node.js >=24.15.0 且 <25、pnpm 11.5.2。

# 尚未安装 pnpm 时：npm install --global pnpm@11.5.2
git clone https://github.com/wkylin/pro-react-admin.git
cd pro-react-admin
pnpm install --frozen-lockfile
pnpm run project:create myApp --preset enterprise
PROJECT=myApp pnpm start

安全预设默认使用 Vite，生成独立项目并启动前端与 Enterprise API。首次启动会创建隔离的本地 SQLite 演示租户；访问终端打印的地址，使用登录页提供的本地演示账号。创建结果、可修改范围和生产配置见多项目与脚手架。

浏览展示应用

只想查看全部演示场景时，在仓库根目录运行 pnpm start。访问终端打印的 /#/signin 地址，点击 admin@test.com 自动填充当前浏览器生成的演示密码，再登录并完成滑块验证；没有统一固定密码。展示应用和本地 API 一起启动，开发埋点使用内存，无需 MongoDB。

演示账号和管理数据由应用内的权限 mock 与 src/features/administration/api/demoProvider.ts 提供，不需要额外启动假接口服务；真实租户模式则调用 server/enterprise/。

Webpack / Vite 构建选择

同一份应用与组件源码支持两套构建器。展示应用与既有示例默认使用 Webpack；新建的安全项目预设默认使用 Vite。设置 BUILD_TOOL=vite 后，start、project:dev、project:build、mfe:* 和 build:pages 使用 Vite。应用也可在命令后传 --bundler=vite，该参数优先于环境变量。

pnpm run dev:webpack                 # Webpack 应用与本地 API
pnpm run dev:vite                    # Vite 应用与本地 API
pnpm run build:webpack              # 输出 dist
pnpm run build:vite                 # 输出 dist-vite
pnpm run build:stats                # Webpack 统计与交互图
pnpm run build:stats:vite           # Vite 统计与交互图
pnpm run analyze:report             # 预览 http://localhost:8766
pnpm run preview:vite               # 预览 http://localhost:5174
pnpm run test:e2e:vite              # 验证 dist-vite
pnpm run project:build projectA --bundler=vite
BUILD_TOOL=vite pnpm run build:mf:vercel

dev:webpack 和 dev:vite 都会启动本地 API；只需前端时使用 pnpm run start:web 或 BUILD_TOOL=vite pnpm run start:web。多项目 Vite 默认输出 dist-vite-<项目名>；BUILD_TOOL=vite pnpm run build:pages 和微前端聚合构建会按部署契约写入既有发布目录。Storybook 使用 storybook:vite / build-storybook:vite（端口 6008、输出 storybook-static-vite），组件库使用 build:lib:vite。这些命令的默认 Webpack 对应项分别是 storybook / build-storybook 和 build:lib。两套组件库构建都写入 packages/wui-react/dist，请顺序运行。Windows 下用 pnpm exec cross-env BUILD_TOOL=vite pnpm run ... 设置环境变量；更多 Storybook 命令见 Storybook 指南。

构建统计和交互图位于 artifacts/build/<webpack|vite>/<项目名>/，不会提交或部署。生产 Sentry source map 上传需配置服务端 SENTRY_AUTH_TOKEN，并显式设置 SENTRY_SOURCE_MAP=map；见构建指南。

应用组件从 @platform/config/env 读取公开变量，不直接使用 process.env 或 import.meta.env；Webpack 和 Vite 共用相同的白名单与 .env 覆盖顺序。新增构建命令后运行 pnpm run check:scripts，逐项校验所有脚本的入口与引用。

所有后续命令均在仓库根目录执行；切换场景前用 Ctrl+C 停止旧服务。编译完成后手动打开浏览器，端口以终端输出为准。完整步骤、环境切换及排查见快速上手指南。

测试与报告

pnpm run test:jest                  # 贴近源码的单元测试
pnpm run test:coverage              # 单元测试与代码覆盖率
pnpm run test:e2e:typecheck         # 浏览器用例与配置类型检查
pnpm run test:e2e                   # Webpack 浏览器测试，需先 build:webpack
pnpm run test:e2e:vite              # Vite 浏览器测试，需先 build:vite
pnpm run test:report                # 浏览 http://localhost:8765

测试基础设施统一位于 tests/，生成结果保存在被 Git 忽略的 tests/reports/。总览可以查看 Jest 逐项结果、行/语句/分支/函数覆盖率及各场景的 Playwright 报告。更多入口与环境要求见质量门禁。

本地环境模板为 .env.development.local.example，首次运行可在根目录创建 .env.development.local：

node --input-type=module -e "import fs from 'node:fs'; if (!fs.existsSync('.env.development.local')) fs.copyFileSync('.env.development.local.example', '.env.development.local')"

实际文件被 Git 忽略；公开演示默认值在共享 .env 中，本地模板不包含密码，已有配置会保留。变量说明和开发/生产加载规则见本地环境文件。

场景	命令	默认地址 / 输出	登录账户
默认应用与 API	`pnpm start`	Web 从 8080 起、API 从 5200 起	`admin@test.com` 等演示账号，密码由浏览器生成
仅默认前端	`pnpm run start:web`	8080	同上
企业本地全栈	`pnpm run start:enterprise` 或 `pnpm run start:enterprise:full`	Web 从 8080 起、API 从 5200 起	`demo` / `admin@demo.local` / `DemoAdmin123!`
企业浏览器演示	`pnpm exec cross-env REACT_APP_USE_MOCK=true pnpm run start:enterprise`	Web 从 8080 起、API 从 5200 起	`admin@test.com` 等浏览器演示账号
多项目	`pnpm run project:dev projectA` / `projectB`	默认 8080，可设置 `PORT`	projectA 使用演示账号；projectB 无需登录
微前端	分别启动三个 `start:mf:*`，见下文	Shell 8080、Remote 8081/8082	公开通信示例，无需登录
本地 lib	`pnpm run prepare:lib:release`	`packages/wui-react/dist`	不适用
自建租户登录	配置并初始化后 `pnpm run start:enterprise`	Web 从 8080 起、API 从 5200 起	初始化时设置的租户 ID、邮箱和自选密码

当前开发机的隔离预览账户另记在 Git 忽略的 docs/LOCAL_PREVIEW.local.md；该文件不随仓库分发，预览账号也不是项目默认账号。

默认应用和企业演示

默认应用使用共享 .env 中的 REACT_APP_USE_MOCK=true。Enterprise 开发入口默认使用仓库内的真实 Node API 和隔离的 SQLite 演示库 api/data/enterprise-demo.sqlite；首次本地启动自动创建租户 demo、邮箱 admin@demo.local、密码 DemoAdmin123!，登录页可一键填入。数据会在重启后保留，修改密码后应使用新密码。该演示库和验证器密钥被 Git 忽略；默认演示库被另一实例占用时，新实例会按 API 端口使用独立的 enterprise-demo-<端口>.sqlite，终端显示实际路径。配置自建数据库、引导租户或外部 API 时不会自动创建或切换数据库。两个企业启动命令等效，都从 5200 开始寻找 API 空闲端口。前端端口也会自动选择；访问终端打印的 Open Enterprise 地址，不要继续使用被其它项目占用的旧标签页。

本地 demo 管理员还可使用左侧“租户管理”查看租户 ID 和管理租户，“权限管理”按角色分配权限。自建数据库的平台管理员须由运维人员显式授权，普通租户管理员不能跨租户操作；删除租户采用可恢复的停用方式。配置和权限边界见企业资源指南。

Enterprise 入口若显式开启 Mock，则使用浏览器演示账号。企业入口包含工作台、用户、角色、审计管理及业务页面模板；浏览器演示完整体验使用 admin@test.com。其它账号为 manager@test.com、business@test.com、user@test.com，可退出登录后切换，对比权限。点击登录页账号会填入该浏览器生成的密码，没有统一固定密码。页面模板的申请记录只在浏览器会话内，不写企业 API。

# 企业浏览器演示：同时启动前端和 Node API，企业登录使用 Mock
pnpm exec cross-env REACT_APP_USE_MOCK=true pnpm run start:enterprise

登录后访问 /#/administration/users、/#/administration/roles、/#/administration/audit。演示数据刷新后重置，编辑演示角色不会改变测试账号授权，也不会创建可登录的新用户。

构建并静态预览，默认应用和企业入口二选一：

# 默认应用：dist，预览 http://localhost:5000/#/signin
pnpm run build:stats
pnpm run serve:dist

# 企业入口：dist-enterprise，预览 http://localhost:5000/#/signin
pnpm exec cross-env REACT_APP_USE_MOCK=true pnpm run build:enterprise:stats
PROJECT=enterprise pnpm run serve:dist

环境前缀写法适用于 macOS/Linux；Windows 使用 pnpm exec cross-env PROJECT=enterprise pnpm run serve:dist。静态预览不提供 API 代理，真实登录的构建预览另见下文指南。

多项目

pnpm run project:list
pnpm run project:doctor

# 终端 1：projectA，http://localhost:8091/#/signin
pnpm exec cross-env PORT=8091 pnpm run project:dev projectA

# 终端 2：projectB，http://localhost:8092/#/projectB/home
pnpm exec cross-env PORT=8092 pnpm run project:dev projectB

projectA 复用展示路由，projectB 是公开示例，无需登录。构建后用 PROJECT 选择对应预览目录：

pnpm run project:build projectA --stats
PROJECT=projectA pnpm run serve:dist

projectB 将上述项目名替换为 projectB；输出分别是 dist-projectA、dist-projectB，静态预览端口为 5000。新增项目可先运行 pnpm run project:create customer --dry-run 查看计划，再运行 pnpm run project:create customer 和 pnpm run project:dev customer。详见多项目指南。

微前端

先确保 8080/8081/8082 可用，在三个终端分别运行：

# 终端 1：Remote A，8081
pnpm run start:mf:projectA

# 终端 2：Remote B，8082
pnpm run start:mf:projectB

# 终端 3：Shell，8080
pnpm run start:mf:shell

编译完成后访问 http://localhost:8080/#/portal，通过 /#/projectA、/#/projectB 查看公开 Remote 通信示例。三个命令仅启动前端。

# 聚合构建及本地预览，不执行 Vercel 部署
pnpm run build:mf:vercel
pnpm run check:mfe-artifacts
pnpm exec serve -s dist-vercel -l 5080

访问 http://localhost:5080/#/portal。组合产物在 dist-vercel，同时重建 Shell 和两个 Remote 的独立输出目录；聚合预览使用 dist-vercel。详见微前端指南。

本地构建 lib

# 只构建 ESM / CJS / CSS / 类型声明
pnpm run build:lib

# 完整准备、包契约、消费 smoke 和体积检查
pnpm run prepare:lib:release
npm pack ./packages/wui-react --dry-run --ignore-scripts

输出为 packages/wui-react/dist，以上命令不会发布到 npm。查看组件示例运行 pnpm run storybook，访问 http://localhost:6006。逐步构建命令见[快速上手](./docs/development/GETTING_STARTED.md#本地构建-lib)，包安装和导入见[组件包用法](NPM_README.md)。

发布到 npmjs，先确认版本未发布并完成完整准备。组件包 6.0.0 可以通过 wui-react-v6.0.0 标签触发 Trusted Publishing；在本机手动发布时，先登录、打包，再上传同一份已验证产物。两种方式只选一种：

pnpm run check:lib-release
pnpm run prepare:lib:release
npm login --registry=https://registry.npmjs.org/ --auth-type=web
npm whoami --registry=https://registry.npmjs.org/
node --input-type=module -e "import fs from 'node:fs'; fs.mkdirSync('artifacts/npm', {recursive:true})"
npm pack ./packages/wui-react --pack-destination artifacts/npm --ignore-scripts
npm publish ./artifacts/npm/w.ui-wui-react-6.0.0.tgz --access public --tag latest --registry=https://registry.npmjs.org/ --ignore-scripts
npm view @w.ui/wui-react@6.0.0 version --registry=https://registry.npmjs.org/

已发布版本不能覆盖；更新时升级组件包版本并使用对应 tarball 文件名。--ignore-scripts 仅用于上传已完整验证的固定产物。Node 工具构建替代命令、beta 通道、发布核验、GitHub Trusted Publishing 和常见问题见组件库构建与 npmjs 发布指南。

如果登录成功后发布仍提示需要两步验证，在自己的终端运行 npm profile enable-2fa auth-and-writes 完成设置，或按现有 2FA 提示认证，再重试同一 tarball。具体命令见发布 2FA。

Storybook 当前源码预览

公共包的 12 个组件、共享 UI 和 components 的全部直接 UI 入口都有 stories，共 157 个入口；从当前源码预览，不需要先构建 lib。

npm run storybook
# 开发预览：http://localhost:6006

pnpm run check:stories
pnpm run typecheck:storybook
npm run build-storybook
node scripts/validate-stories.mjs --built
npm run serve:storybook
# 静态预览：http://localhost:6007

更新配置后先按 Ctrl+C 停止旧 Storybook，执行 npm run storybook:reset 清理专用缓存并启动；普通启动已显式设置 BABEL_ENV=storybook，避免注入应用的 React Refresh。在线入口为 Storybook。新示例上线需要推送代码并等待 Pages workflow 完成。 $RefreshSig$ 排查、样式/Provider、源码分组和 Vercel 独立部署见 Storybook 指南。

发布全部 GitHub Pages 演示

仓库 Settings → Pages → Source 选择 GitHub Actions；推送 main 自动发布全部场景。手动 workflow 可选择默认应用、企业演示、微前端、多项目或仅 Storybook。

# 本地构建，不上传
PAGES_TARGET=all pnpm run build:pages
pnpm run check:pages

# gh 已登录后手动触发远端部署
gh workflow run deploy-gh-pages.yml --ref main -f target=all

输出 dist-combined：默认应用在根，企业演示在 /enterprise/，普通项目在 /projects/projectA/ 与 /projects/projectB/，微前端在 /mfe/，组件站在 /storybook/。这些路径相对于实际 Pages base，Fork 和自定义域名从 Pages 配置推断。完整命令与 v6.0.0 标签/Release 流程见 GitHub 部署指南。

真实用户登录和权限设置

停止演示服务，创建或修改根 .env.development.local，将示例密码替换为自己的 12..256 字符密码：

REACT_APP_USE_MOCK=false
APP_BASE_URL=
ENTERPRISE_ENABLED=true
TRACKING_STORE=memory
TRACKING_API_PORT=5200
ENTERPRISE_BOOTSTRAP_TENANT=acme
ENTERPRISE_BOOTSTRAP_TENANT_NAME=Acme
ENTERPRISE_BOOTSTRAP_NAME=Administrator
ENTERPRISE_BOOTSTRAP_EMAIL=admin@example.com
ENTERPRISE_BOOTSTRAP_PASSWORD="替换为你自己的12至256字符密码"

# 每个租户只初始化一次；已有租户不能通过此命令重置密码
pnpm run api:bootstrap

成功后删除配置文件中的五项 ENTERPRISE_BOOTSTRAP_*，保留其它配置，再启动：

pnpm run start:enterprise:full

访问 http://localhost:8080/#/signin，填租户 acme、邮箱 admin@example.com 和初始化密码。业务数据库默认 api/data/enterprise.sqlite，刷新和重启保留数据。浏览器 Mock 账号和本地 demo 租户账号都不属于这个自建租户。

管理员在角色管理添加 viewer，授予 home:read、user:read。
在用户管理添加真实邮箱和 12..256 字符密码，分配 viewer，状态设为启用。
退出后用同一租户和新用户凭据登录，验证可读工作台、用户列表，不能修改用户或访问角色、审计页。

用户操作权限为 user:create、user:update、user:delete，角色操作为 role:create、role:update、role:delete，审计为 audit:read；创建/编辑用户的角色选项还需要 role:read。用户运营角色可配置 home:read、user:*、role:read。服务端限制授予范围，账号停用和密码重置等操作会撤销会话；角色撤权在下一次服务请求生效，客户端聚焦或重新登录可同步。

同一 origin 的标签页共享当前登录身份，比较多个账号请使用独立无痕会话。真实模式的构建预览先停止全栈开发服务，再分别运行：

# 终端 1：沿用上面的开发配置，启动真实 API
pnpm --filter api dev

# 终端 2：关闭 mock 并指定本地 API 地址，再预览构建结果
pnpm exec cross-env APP_BASE_URL=http://127.0.0.1:5200 pnpm run build:enterprise:api
PROJECT=enterprise pnpm run serve:dist

访问 http://localhost:5000/#/signin。此构建会覆盖企业演示的 dist-enterprise；API 需要一直运行。开发和生产本地环境文件分别是 .env.development.local、.env.production.local，修改后需重启或重新构建。更多配置见真实模式构建预览和企业资源接入。

Vercel 企业登录与数据库

默认站点 https://pro-react-admin.vercel.app 的 GitHub 登录接受任意 GitHub 账号，登录后固定为普通演示用户，不关联企业租户。部署需在 Vercel Production 配置 OAuth 凭据和签名密钥，再构建静态应用与一个同源函数：

pnpm run build:production
pnpm run vercel:prepare:default
vercel deploy --prebuilt --prod

GitHub OAuth App 的精确回调、环境变量及验收步骤见 Vercel GitHub 登录。纯静态 GitHub Pages 不提供此登录方式。

纯在线演示无需数据库，关联企业 Vercel 项目后执行：

pnpm exec cross-env REACT_APP_USE_MOCK=true APP_BASE_URL= PUBLIC_URL=/ pnpm run build:enterprise:stats
pnpm run vercel:prepare:enterprise
vercel deploy --prebuilt --prod

真实登录有两种部署方式：独立 Vercel Enterprise API + Neon PostgreSQL（完整部署指南），或 Vercel 前端 + 带持久卷的 SQLite API 主机（SQLite 部署指南）。文件型 SQLite 不放在 Vercel Functions 中。PostgreSQL 路径提供显式建表、连接池、完整 Enterprise API、数据库登录限速和资源轮询；SQLite 路径继续提供单实例 WebSocket 事件。

API 主机初始化并启动后，在开发机部署真实前端：

pnpm exec cross-env APP_BASE_URL=https://api.example.com PUBLIC_URL=/ pnpm run build:enterprise:api
pnpm run vercel:prepare:enterprise
vercel deploy --prebuilt --prod

将示例 API 地址换为自己的 HTTPS 域名，使用真实租户、邮箱和密码登录。选择 Neon 时，先按 Vercel + Neon 指南创建独立 API 项目、数据库与表；桌面客户端连接见 DBeaver 连接指南。选择 SQLite 时，服务器完整命令及只读演示用户创建见 Vercel 与 SQLite 指南。

工程能力

明确的 app/features/platform/shared/UI 包边界，类型与依赖方向门禁。
一处维护权限、标题和菜单元数据；导航与搜索同步授权，已挂载页面响应撤权。
每个应用根独立 Store 和页面缓存，项目偏好按命名空间保存。
注册表驱动开发、构建、预览、清理和部署，支持 doctor、dry-run 与项目脚手架。
可替换的类型化 DataProvider、REST adapter、用户/角色 CRUD 和只读审计示例。
可选真实租户/RBAC 后端，服务端会话撤销、持久化 CRUD 与事务审计；会话隔离的资源缓存和写入失效。
编译期业务模块契约，统一路由、Provider、资源目录、依赖和权限控制的 Header 插槽。
展示与企业路由独立，重型页面和可选效果按需加载，生产包体积门禁。

常用命令

pnpm run project:doctor
pnpm run project:create customer --dry-run
pnpm run project:dev projectA
pnpm run build:enterprise:stats
pnpm run test:e2e:enterprise
pnpm run ci:quality

Docker 静态镜像、Vercel/GitHub Pages 与组件库发布见文档。根应用为 private，UI 包独立构建和发布。

维护入口

工程已具备单实例自托管的租户/RBAC、持久化与事务审计基础。SSO、多组织成员关系、分布式服务、运行期插件和全仓 strict 仍需继续完善，详见架构和对标文档。

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.github		.github
.husky		.husky
.qoder/skills		.qoder/skills
.storybook		.storybook
.vscode		.vscode
agent/skills		agent/skills
api		api
apps/enterprise-api		apps/enterprise-api
build		build
config		config
deploy		deploy
docs		docs
packages/wui-react		packages/wui-react
public		public
scripts		scripts
server		server
src		src
tests		tests
typings		typings
.deepsource.toml		.deepsource.toml
.editorconfig		.editorconfig
.env		.env
.env.development.local.example		.env.development.local.example
.env.enterprise.postgres.local.example		.env.enterprise.postgres.local.example
.env.enterprise.production.local.example		.env.enterprise.production.local.example
.env.production		.env.production
.env.production.local.example		.env.production.local.example
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.stylelintrc.json		.stylelintrc.json
.vercelignore		.vercelignore
.versionrc.json		.versionrc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NPM_README.md		NPM_README.md
README.md		README.md
SECURITY.md		SECURITY.md
babel.config.cjs		babel.config.cjs
compose.enterprise.yaml		compose.enterprise.yaml
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.js		postcss.config.js
qodana.yaml		qodana.yaml
skills-lock.json		skills-lock.json
sonar-project.properties		sonar-project.properties
tsconfig.api.json		tsconfig.api.json
tsconfig.json		tsconfig.json
tsconfig.lib.json		tsconfig.lib.json
tsconfig.paths.json		tsconfig.paths.json
tsconfig.storybook.json		tsconfig.storybook.json
tsconfig.strict-boundaries.json		tsconfig.strict-boundaries.json
vercel.enterprise.json		vercel.enterprise.json
vercel.json		vercel.json
vercel.mfe.json		vercel.mfe.json
vercel.projectA.json		vercel.projectA.json
vercel.projectB.json		vercel.projectB.json
vercel.shell.json		vercel.shell.json
vercel.storybook.json		vercel.storybook.json

Navigation Menu

Repository navigation

About

Repository files navigation

Pro React Admin

线上预览

快速上手

浏览展示应用

Webpack / Vite 构建选择

测试与报告

默认应用和企业演示

多项目

微前端

本地构建 lib

Storybook 当前源码预览

发布全部 GitHub Pages 演示

真实用户登录和权限设置

Vercel 企业登录与数据库

工程能力

常用命令

维护入口

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Pro React Admin

线上预览

快速上手

浏览展示应用

Webpack / Vite 构建选择

测试与报告

默认应用和企业演示

多项目

微前端

本地构建 lib

Storybook 当前源码预览

发布全部 GitHub Pages 演示

真实用户登录和权限设置

Vercel 企业登录与数据库

工程能力

常用命令

维护入口

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages