# serverpod_admin

**Repository Path**: coderxslee/serverpod_admin

## Basic Information

- **Project Name**: serverpod_admin
- **Description**: serverpod_admin
- **Primary Language**: Dart
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2025-01-11
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">📚 Serverpod Admin 全栈项目</h1>

<p align="center">
  Serverpod 统一后端 · Vue 3 管理端 · Flutter 移动端
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Serverpod-4.0.3-blue" alt="Serverpod">
  <img src="https://img.shields.io/badge/Dart-3.12+-blue" alt="Dart">
  <img src="https://img.shields.io/badge/Flutter-3.47.4-blue" alt="Flutter">
  <img src="https://img.shields.io/badge/Vue-3.5-42b883" alt="Vue">
  <img src="https://img.shields.io/badge/TypeScript-5.9-3178c6" alt="TypeScript">
  <img src="https://img.shields.io/badge/Vite-7-646cff" alt="Vite">
  <img src="https://img.shields.io/badge/PostgreSQL-16+-336791" alt="PostgreSQL">
  <img src="https://img.shields.io/badge/Redis-6.2-dc382d" alt="Redis">
</p>

---

## 📖 项目简介

本项目由三个端组成，一个后端同时服务 PC 管理端和移动端：

| 端 | 目录 | 定位 |
| --- | --- | --- |
| **后端 API** | `backend/` | Serverpod 服务端，提供 `/api/**` REST 接口、ORM 与数据库迁移 |
| **PC 管理端** | `frontend/web/` | 基于 Gi-demo（Gi Admin Pro）的 Vue 3 中后台 |
| **移动端** | `frontend/app/` | Flutter 原生 App（Android / iOS） |

后端采用 **Dart 原生 pub workspace**（Monorepo）管理，`serverpod_admin_server`、`serverpod_admin_client`、`serverpod_crud` 三个成员包共享一份 `pubspec.lock` 与 `.dart_tool`，Serverpod 版本在根 `pubspec.yaml` 的 `dependency_overrides` 中统一锁定。

> 目录名与包名一致：`serverpod_admin_server`（server 包）/ `serverpod_admin_client`（client 包）。Serverpod 由包名推导迁移模块名（去掉 `_server` 后缀，即 `serverpod_admin`），**升级已有数据库前必须先执行 `deploy/rename-migration-module.sql`**，否则启动时会把历史迁移当成未执行并重放建表语句。

> 后端接口已全面转向 **REST**（`/api/**`，由 webServer 的 8082 端口提供）。`serverpod_admin_client` 不再承载业务客户端职责，仅作为 `serverpod generate` 强制要求的生成输出目标保留；目录名与包名对齐后，`config/generator.yaml` 不再需要 `client_package_path`。

---

## 🧱 技术栈

### 后端（`backend/`）

- **框架**：Serverpod 4.0.3
- **语言 / SDK**：Dart 3.12+（Flutter 3.47.4，FVM 锁定）
- **数据库**：PostgreSQL 16（`pgvector/pgvector:pg16` 镜像）
- **缓存**：Redis 6.2
- **接口风格**：REST，路由位于 `serverpod_admin_server/lib/src/web/routes/api/`（`core` / `system` / `zhongyi` / `zhouyi` / `airtable`）
- **鉴权与权限**：登录认证 + 用户 / 角色 / 部门 / 菜单权限，另有字典、操作日志、文件上传、App 版本发布等系统路由
- **部署**：Docker 镜像 + Docker Compose（Nginx 1.25 反向代理）

### PC 管理端（`frontend/web/`）

- **模板**：Gi-demo（Gi Admin Pro），保留其 `Gi*` 全局组件体系
- **框架**：Vue 3.5 + TypeScript 5.9
- **构建**：Vite 7（`pnpm`，`@` → `src/`，`~` → 项目根）
- **UI**：Arco Design Vue 2.58 + `@arco-themes/vue-gi-demo`
- **状态 / 路由**：Pinia 3（含持久化插件）、Vue Router 4
- **图表 / 编辑器**：ECharts 6、CodeMirror 6、WangEditor、md-editor-v3
- **代码规范**：ESLint 9（`@antfu/eslint-config`）+ Stylelint + `vue-tsc` 类型检查

### 移动端（`frontend/app/`）

- **框架**：Flutter 3.47.4（FVM 锁定），Dart 3
- **状态 / 路由**：GetX 5
- **UI**：TDesign Flutter + Material
- **本地存储**：Floor（`build_runner` 生成）
- **原生能力**：扫码、相机/相册、图片压缩与裁剪、友盟统计与推送、权限管理
- **构建产物**：Android / iOS

---

## 📂 目录结构

```
serverpod_admin/
├── backend/                         # Serverpod 后端（Dart pub workspace）
│   ├── pubspec.yaml                 # workspace 根配置，统一 Serverpod 版本
│   ├── serverpod_admin_server/      # server 包：REST 路由 / ORM 模型 / migrations
│   │   ├── lib/src/web/routes/api/  #   业务路由（system / zhongyi / zhouyi / airtable）
│   │   ├── lib/src/models/          #   ORM 模型（spy.yaml）
│   │   ├── migrations/              #   数据库迁移
│   │   ├── config/                  #   环境配置（development / test / production）
│   │   ├── docker/                  #   development / production 编排
│   │   └── start.sh                 #   本地启动菜单（起容器 / 迁移 / 启服务）
│   ├── serverpod_admin_client/      # client 包：仅作 serverpod generate 输出目标
│   └── serverpod_crud/              # 通用 CRUD 能力包
├── frontend/
│   ├── web/                         # Gi-demo Vue 3 管理端
│   └── app/                         # Flutter 移动端（云门医盘）
├── deploy/                          # 服务器侧部署脚本、运维 SQL、远程部署配置
├── docs/images/                     # 文档配图
├── build_image.sh                   # 后端镜像构建并导出 tar.gz
├── request_letsencrypt.sh           # Let's Encrypt 证书申请
└── ssl/                             # 证书文件（不进版本库）
```

---

## ✨ 核心特性

- 🚀 **单一后端**：一套 Serverpod 服务同时支撑 PC 管理端与移动端，接口统一在 `/api/**`
- 🧩 **Monorepo**：Dart pub workspace + 管理端独立前端工程，版本与依赖集中管理
- 🗄️ **数据层**：PostgreSQL 16（支持 pgvector）+ Redis，模型与迁移由 Serverpod ORM 驱动
- 🔐 **权限体系**：用户 / 角色 / 部门 / 菜单 + 操作日志，管理端菜单由数据库动态下发
- 📱 **多端覆盖**：Vue 3 管理后台 + Flutter 原生 App（Android / iOS）
- 🐳 **可回滚部署**：镜像化后端、静态资源原子切换、健康检查与失败自动回滚

---

## 🚀 快速开始

### 环境要求

- Flutter **3.47.4**（由 FVM 管理，`.fvmrc` 已锁定，仓库内执行 `fvm install`）
- Node.js 18+ 与 **pnpm**（管理端）
- Docker + Docker Compose（本地 PostgreSQL / Redis）
- Serverpod CLI，版本需与 workspace 的 **4.0.3** 对齐

### 1. 后端

```bash
cd backend
fvm install
fvm flutter pub get          # workspace 根执行一次，三个成员包一并解析

cd serverpod_admin_server
cp .env/.env.example .env/.env.development   # 按需修改数据库 / Redis 口令
./start.sh                                    # 交互菜单：起容器 → 迁移 → 启动服务
```

服务端口：

| 服务 | 端口 | 说明 |
| --- | --- | --- |
| `apiServer` | 8080 | Serverpod 主服务（typed Endpoint 端口，业务已不再使用） |
| `insightsServer` | 8081 | 监控与调试 |
| `webServer` | 8082 | **REST 接口入口**，业务路径统一为 `/api/**` |

数据库与 Redis 口令存放在 `serverpod_admin_server/config/passwords.yaml`，容器口令存放在 `.env/.env.*`，两者都不要提交。

### 2. PC 管理端

```bash
cd frontend/web
pnpm install
pnpm dev            # 开发服务器
pnpm build          # 生产构建（产物在 dist/）
```

- 接口前缀由 `.env.development` / `.env.production` 的 `VITE_API_PREFIX` 控制，开发环境默认指向 `http://localhost:8082/api`
- 生产构建 `VITE_BASE = '/web/'`，因此 Nginx 必须把 `/api` 反代到 **8082**（不是 8080），静态资源挂在 `/web/` 下
- `src/` 之外的 `mock/` 提供 Mock 数据，可脱离后端联调

### 3. 移动端

```bash
cd frontend/app
fvm install
fvm flutter pub get
fvm flutter run          # 需先连真机或启动模拟器
```

接口地址在 `lib/main_api.dart`（生产 `https://a.app.yizhuanyiyuan.cn`，内网测试 `http://192.168.100.74:8082`）。

### 4. 生成代码

修改服务端模型后重新生成：

```bash
cd backend/serverpod_admin_server
serverpod generate
```

---

## 📦 构建与部署

| 步骤 | 命令 / 文件 | 说明 |
| --- | --- | --- |
| 后端镜像 | `./build_image.sh` | 构建 `backend/` 镜像并导出到 `backend/dist/*.tar.gz` |
| 后端发布 | `deploy/deploy-backend.sh` | 在服务器执行：载入镜像 → 迁移 → compose 重启 → 健康检查 → 失败回滚 |
| 前端发布 | `deploy/deploy-frontend.sh` | 在服务器执行：解压 `frontend/web/dist.tar.gz` 校验后原子切换 |
| 远程部署 | `deploy/config.serverpod_admin.yaml` | 一键远端发布配置（本地构建 + 上传） |
| 模块改名 | `deploy/rename-migration-module.sql` | 已有数据库升级前执行一次（`flutter_web` → `serverpod_admin`） |

生产编排见 `backend/serverpod_admin_server/docker/production/docker-compose.yaml`：`apiServer` 只监听本机 8080/8082，对外仅暴露 Nginx 的 80/443。

---

## 📝 文档

- [Serverpod 官方文档](https://docs.serverpod.dev/)
- [Flutter 官方文档](https://docs.flutter.dev/)
- [Vue 3 官方文档](https://cn.vuejs.org/)
- [Vite 官方文档](https://cn.vitejs.dev/)
- [Arco Design Vue](https://arco.design/vue)
- [Gi-demo 仓库](https://github.com/lin-97/gi-demo)
- [管理端说明](frontend/web/README.md)
- [移动端说明](frontend/app/README.md)

---

## 🤝 参与贡献

1. Fork 本仓库
2. 创建特性分支（`git checkout -b feature/AmazingFeature`）
3. 提交更改（`git commit -m 'Add some AmazingFeature'`）
4. 推送分支（`git push origin feature/AmazingFeature`）
5. 提交 Pull Request

---

## 📄 许可证

木兰宽松许可证，第 2 版，详见 [backend/LICENSE](backend/LICENSE)。

---

## 📧 联系方式

- 📮 提交 Issue
- 💬 **添加微信**：扫描下方二维码

<p align="center">
  <img src="docs/images/wechat-qrcode.jpg" width="300" alt="微信二维码">
</p>

<p align="center">
  <i>扫一扫上面的二维码图案，加我为朋友</i>
</p>

---

<p align="center">
  Made with ❤️ by coderxslee
</p>