# SertorAdmin 尚途全栈开发框架

**Repository Path**: scloud1688/sertor-admin

## Basic Information

- **Project Name**: SertorAdmin 尚途全栈开发框架
- **Description**: 在成熟管理后台能力（RBAC、系统设置、上传等）之上，补齐 C 端 UniApp、多终端登录与注册策略、页面装修与公告运营 等常见手机端业务所需的后台配置与接口，适合作为商城、会员、工具类 App / 小程序的起步脚手架。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://www.scloud.ltd/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-15
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 免费, 完全开源, thinkphp8

## README

# SertorAdmin


**尚途移动端全栈开发框架**：在成熟管理后台能力（RBAC、系统设置、上传等）之上，补齐 **C 端 UniApp**、**多终端登录与注册策略**、**页面装修与公告运营** 等常见手机端业务所需的后台配置与接口，适合作为商城、会员、工具类 App / 小程序的起步脚手架。

| 语言 | 说明 |
|------|------|
| 中文 | 本文档 |
| English | [README.en.md](./README.en.md) |

---

## 项目定位

| 端 | 说明 |
|------|------|
| 后端 | ThinkPHP 8 多应用：`adminapi` 供运营后台使用，`api` 供 H5 / 微信小程序 / 抖音小程序 / APP 调用 |
| 管理后台 | Vue 3 + Element Plus，具备 RBAC、系统设置、上传等基础能力 |
| C 端 | UniApp 3 客户端，覆盖渠道与登录策略、首页装修 / 公告 / 客服等移动端配套能力 |

---

## 适用场景

- 需要 **后台可配置** 的 App / H5 / 微信小程序 / 抖音小程序
- 希望 **登录方式、绑手机、完善资料** 可按端灵活开关，而非写死在客户端
- 首页 **轮播、导航、公告** 由运营在后台维护，客户端拉取渲染
- 在管理后台能力之上快速扩展会员、订单等业务模块

---

## 技术栈

| 端 | 技术 |
|----|------|
| 后端 | ThinkPHP 8、think-orm、think-multi-app（`adminapi` + `api`） |
| 管理后台 | Vue 3.5、Vite 6、TypeScript、Element Plus、Pinia、VueUse |
| C 端 | UniApp 3（Vue 3 + TS）、Vite 5、uview-plus、Pinia |
| 数据库 | MySQL 5.7+ / 8.0，表前缀默认 `sc_` |

**C 端运行形态（已适配）**

| 形态 | 说明 |
|------|------|
| H5 | 可部署于 `server/public/mobile`，与 PHP 同源访问 `/api` |
| 微信小程序 | 登录、手机号授权换绑等 |
| 抖音小程序 | 登录、手机号授权等 |
| APP | 账号密码 / 短信等（按后台策略） |

---

## 功能概览

### 管理后台

- 登录 / 登出、Token 会话、安装锁、演示站只读模式
- **权限**：菜单（目录 / 菜单 / 按钮）、角色、管理员；**GrantScope**（子集授权）
- **系统设置**：项目信息、备案、政策协议（富文本，图片相对路径入库）
- **布局与主题**：侧栏、主题色、黑暗模式、多页签
- **上传**：`storage_scene` 分场景目录，可选 GD 压缩裁切
- **用户管理**：C 端用户列表、详情、禁用、重置密码、踢下线、导出
- **开发设置**：微信 / 抖音 / APP 渠道参数、**各端注册登录策略**（维护模式、协议勾选、绑手机、完善资料门控等）
- **页面装修**：首页轮播、宫格导航（图片选填；无图时 C 端首字 / 标题占位）、可视化跳转（页面 / 公告 / 不跳转）
- **内容运营**：公告分类与公告、富文本编辑
- **客服配置**：联系方式等在 C 端「联系客服」展示

### C 端 UniApp

- **首页**：轮播、导航、公告入口；装修数据接口驱动
- **登录注册**：账号密码、短信验证码、图形验证码；协议确认弹窗
- **多终端策略**：通过 `bootstrap` 拉取与后台一致的 `auth_gate`，动态展示登录方式及绑手机 / 完善资料引导
- **我的**：个人资料、账户安全（改密、换绑手机、第三方绑定解绑）
- **小程序**：微信 / 抖音 `getPhoneNumber` 换绑等能力
- **公告**：列表、详情；协议页 `code` 查询

**默认管理端账号**：`root` / `123456`（安装后请立即修改）

---

## 环境要求

| 项 | 要求 |
|----|------|
| PHP | **8.2+**，扩展：`json`、`mbstring`、`openssl`、`pdo_mysql`、`fileinfo`；图片压缩可选 **gd** |
| MySQL | 5.7+ / 8.0，`utf8mb4` |
| Node.js | **18+** |
| 包管理 | **npm**（管理端、UniApp 均以 npm 为例） |
| Composer | 仓库已含 `server/vendor/`，日常克隆**无需** `composer install`；仅升级框架时需要 |
| 微信 / 抖音开发者工具 | 调试小程序时按需安装 |

---

## 目录结构

```text
SertorAdmin/
├── server/                      # 后端（含 vendor，可直接 php think）
│   ├── app/adminapi/            # 管理端 API
│   ├── app/api/                 # C 端 API（登录、首页、用户、公告等）
│   ├── public/                  # Web 入口（站点根目录指向此处）
│   │   └── mobile/              # H5 生产构建产物目录（npm run build:h5 后拷贝）
│   ├── sql/
│   │   ├── sertor_admin_1.6.1.sql       # 全量库（当前版本）
│   │   ├── sertor_admin_1.0.0.sql       # 初始基线
│   │   └── upgrade/                     # 增量升级脚本
│   └── .env.example
├── admin/                       # 管理后台前端（Vue3 + Element Plus）
├── uniapp/                      # C 端 UniApp（H5 / 小程序 / APP）
└── docs/                        # 安装、升级、变更说明
```

---

## 命令行工作目录（重要）

| 操作 | 目录 |
|------|------|
| `php think run`、`php think clear`、编辑 `.env` | **`server/`** |
| `composer update`（升级框架时） | **`server/`** |
| `npm install`、`npm run dev`、`npm run build` | **`admin/`** |
| `npm install`、`npm run dev:h5`、`npm run build:h5` 等 | **`uniapp/`** |

> **后端依赖**：克隆后配置 `.env`、导入 SQL 即可运行。仅升级 ThinkPHP 或依赖时在 `server/` 执行 `composer update`（详见 [docs/upgrade.md](docs/upgrade.md)）。

---

## 一、克隆后通用步骤

### 1. 配置后端环境变量

```bash
cd server
# Windows
copy .env.example .env
# Linux / macOS
# cp .env.example .env
```

编辑 `server/.env`（**必须 UTF-8 无 BOM**）：

```ini
DB_HOST = 127.0.0.1
DB_NAME = sertor_admin
DB_USER = root
DB_PASS = 你的密码
DB_PREFIX = sc_

project.unique_identification = sertor_admin
project.web_name = SertorAdmin
```

> `project.unique_identification` 同时作为**密码盐**，改动后所有用户密码需重置。

### 2. 创建数据库并导入

```bash
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS sertor_admin DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p sertor_admin < sql/sertor_admin_1.6.1.sql
```

（在 `server/` 目录下执行。）

若从早期版本仓库升级，请按 [docs/upgrade.md](docs/upgrade.md) 与 [docs/CHANGELOG.md](docs/CHANGELOG.md) 依次执行 `sql/upgrade/` 下脚本。

### 3. 安装锁

导入 SQL 且数据库可连后，访问接口会自动处理；也可手动创建：`server/config/install.lock`。

### 4. 验证后端

```bash
cd server
php think version
php think run
```

另开终端探活（默认 `http://127.0.0.1:8000`）：

```text
GET http://127.0.0.1:8000/adminapi/config/getConfig
GET http://127.0.0.1:8000/api/config/bootstrap
```

均应返回 JSON 且 `code=1`。

---

## 二、管理后台前端（admin）

```bash
cd admin
npm install
npm run dev
```

编辑 `admin/.env.development`（**不要**末尾斜杠）：

```ini
VITE_APP_BASE_URL=http://127.0.0.1:8000
```

- 开发地址：<http://localhost:5173/admin/>
- 接口为 `VITE_APP_BASE_URL` + `adminapi` 前缀；跨域由后端 `CorsMiddleware` 处理

生产构建：

```bash
npm run build
```

构建完成后会自动将 `dist/` 产物覆盖部署到 `../server/public/admin/`，无需手动拷贝。

生产环境 `admin/.env.production` 中 **`VITE_APP_BASE_URL` 留空**，请求同源 `/adminapi/...`。

---

## 三、C 端 UniApp（uniapp）

```bash
cd uniapp
npm install
```

复制环境变量：

```bash
# Windows
copy .env.example .env.development
# Linux / macOS
# cp .env.example .env.development
```

编辑 `uniapp/.env.development`：

```ini
# 与后端同源根地址，不含 /api
VITE_APP_BASE_URL=http://127.0.0.1:8000
```

| 命令 | 说明 |
|------|------|
| `npm run dev:h5` | H5 开发 |
| `npm run build:h5` | H5 生产包 |
| `npm run dev:mp-weixin` | 微信小程序开发 |
| `npm run build:mp-weixin` | 微信小程序构建 |

**H5 生产部署**：将 `uniapp/dist/build/h5` 内容拷贝到 `server/public/mobile/`，浏览器访问 `https://你的域名/mobile/`。此时 H5 使用相对路径 `/api`，无需跨域。

**微信小程序**：在后台「开发设置 → 微信小程序」填写 AppId / Secret；开发者工具中配置 request 合法域名；本地调试可勾选「不校验合法域名」。

**抖音小程序**：在后台配置抖音小程序参数；使用 `mp-toutiao` 相关构建命令（若已加入 package.json）或按 UniApp 文档编译抖音端。

---

## 四、Windows 本地开发（phpEnv）要点

1. phpEnv 使用 **PHP 8.2**，启动 MySQL。
2. 切换 PHP 版本后请**重启 IDE / 终端**，确认 `php -v` 为 8.2。
3. 后端二选一：
   - **推荐**：`cd server && php think run`（默认 8000 端口）
   - **站点模式**：网站根目录指向 `server/public`，PHP 8.2
4. 同时启动 `admin` 与 `uniapp` 的开发命令，三端联调。

| 现象 | 处理 |
|------|------|
| `php -v` 仍是 8.0 | 重启终端；phpEnv 确认已切 8.2 |
| `code=-2` 未安装 | 检查 SQL、`.env` 编码、`install.lock` |
| C 端请求失败 | 核对 `VITE_APP_BASE_URL`、后端是否启动、小程序域名白名单 |
| 前端 `\x00` 报错 | `.vue` 保存为 UTF-8 **无 BOM** |

---

## 五、Linux 生产部署（宝塔）要点

1. 站点根目录：**`/path/to/SertorAdmin/server/public`**
2. PHP **8.2**，扩展齐全；Nginx 配置 ThinkPHP 伪静态
3. 导入 `sql/sertor_admin_1.6.1.sql`，配置 `.env`
4. `runtime`、`public/uploads` 可写
5. 构建并部署 `admin` → `public/admin/`
6. 构建并部署 H5 → `public/mobile/`（可选）
7. 验证：`/adminapi/config/getConfig`、`/api/config/bootstrap`

生产建议 `app_debug = false`。演示站可设 `app_demo = true` 禁止写操作。

详细伪静态、HTTPS、权限说明见 [docs/install.md](docs/install.md)。

---

## 六、升级与增量 SQL

日常 `git pull` 后：

```bash
cd admin && npm install
cd ../uniapp && npm install
cd ../server && php think clear
```

若有库表变更，在 `server/` 下执行 `sql/upgrade/` 对应版本脚本，详见 [docs/upgrade.md](docs/upgrade.md) 与 [docs/CHANGELOG.md](docs/CHANGELOG.md)。

---

## 文档索引

| 文档 | 说明 |
|------|------|
| [docs/install.md](docs/install.md) | 安装细节、安装锁、生产部署、常见问题 |
| [docs/permission.md](docs/permission.md) | 后台权限规则，筛选项与表单选项接口约定 |
| [docs/upgrade.md](docs/upgrade.md) | Composer / ThinkPHP 升级、增量 SQL |
| [docs/CHANGELOG.md](docs/CHANGELOG.md) | 版本与功能变更记录 |
| [docs/README.md](docs/README.md) | 文档目录 |

---

## 开发约定

- 管理端页面组件路径需与 `views` 目录一致，菜单支持扫描联想。
- 筛选项和新增/编辑里的下拉，单独做 `options` / `pickerList` / `formOptions`，**不要写入菜单权限，也不要调其他模块的 `lists` 或 `all`**。详见 [docs/permission.md](docs/permission.md)。
- C 端请求头携带 `terminal`，与后台「注册登录」各端策略对应。
- 富文本图片：入库相对路径、读出绝对路径（`RichContentService`）。
- 页面装修跳转：未选择时保存为 `linkType: none`，与显式「不跳转」一致。
- Windows 下编辑 `.vue` 请保存为 **UTF-8（无 BOM）**。

---

## License

后端 `server/` 含 ThinkPHP 等第三方依赖，见其各自协议；业务代码以仓库根目录 LICENSE 约定为准。