1

README.md

@@ -1,3 +1,44 @@
+# 快速开始
+
+**环境**：Node.js（建议 LTS）、MySQL 5.7+ / 8.x（`utf8mb4`）。
+
+### 1. 安装依赖
+
+- 项目根目录：`npm install`
+- 管理端：`cd admin && npm install`（根目录 `npm run dev` 会进入 `admin`，但首次建议两处各装一次依赖）
+
+### 2. 数据库与 `sql/init.sql`
+
+1. 在 MySQL 中建空库，例如：`CREATE DATABASE your_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;`
+2. `USE your_db;`
+3. 执行 **`sql/init.sql`**（与 `migrations/init.sql` 内容一致）。会 `DROP`/`CREATE` 系统表并写入：默认租户、**超级管理员角色**、用户 **`admin` / `123456`**（MD5 与框架一致）、`sys_title` / `sys_logo`、菜单等。**库名须与下一步 `config.development.js` 里的 `db.database` 一致。**
+4. 需要「演示数据」列表时，再执行 **`sql/tpl_demo.sql`**。
+
+### 3. 配置 `config/config.development.js`
+
+- 填写 **`db`**：`username`、`password`、`database`、`host`、`port`、`dialect: "mysql"`。**框架要求 `password` 非空**（不能留空字符串）。
+- 可选：用环境变量覆盖数据库——`DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME`（与文件内默认值二选一，以你本机为准）。
+- **阿里云 OSS**：本地可保留非空占位 `accessKeyId` / `accessKeySecret` / `bucket`，避免 `sys_file` 依赖加载失败；真实 OSS 再改为控制台密钥，或通过 `ALIYUN_ACCESS_KEY_ID`、`ALIYUN_ACCESS_KEY_SECRET`、`ALIYUN_OSS_URL`、`ALIYUN_OSS_BUCKET` 注入。
+
+### 4. 启动后端
+
+- 根目录：`npm run api`（nodemon）或 `npm start`（`node app.js`）。
+- 默认 **API 端口**见 `config/config.js` 的 `port.node`（模板为 **9098**）。
+- 文档：**`http://localhost:<port>/api/docs`**
+
+### 5. 启动管理端
+
+- 根目录：`npm run dev`（默认 **9000** 端口，见根目录 `package.json` 脚本）。
+- 接口根地址在 **`admin/config/index.js`** 的 `apiUrl`，须与后端端口一致（模板为 `http://localhost:9098/admin_api/`）。
+
+### 6. 登录与排错
+
+- 默认：**`admin` / `123456`**；租户可不传或按 `sys_tenant.code`（如 `default`）。
+- **`sys_file` 加载失败**：检查 `aliyun` 字段是否非空或已配置环境变量。
+- **连库失败**：核对 `db`、防火墙、是否已执行 `init.sql`。
+
+---
+
 # 前后端项目模板
 
 基于 **admin-framework**（管理端 Vue2 + ViewUI）与 **node-core-framework**（Koa2 + Sequelize）的最小可运行骨架，已去掉原 WMS 业务，仅保留一条演示业务链与系统接口。
@@ -10,14 +51,6 @@
 - `api/model/`：业务模型（模板保留 `tpl_demo`、`sys_tenant`）
 - `config/`：`config.js` 白名单、`framework.config.js` 框架项、环境库表连接
 
-## 本地运行
-
-1. 安装依赖：项目根目录 `npm install`，`admin` 目录 `npm install`
-2. 在 MySQL 中创建库并 `USE` 后，执行 **`sql/init.sql`**（或 `migrations/init.sql`，内容一致）：创建系统表并写入默认租户、**超级管理员角色**、用户 **`admin` / `123456`**、**站点标题 `sys_title` 与 Logo `sys_logo`**、菜单树、控件字典等；再按需执行 **`sql/tpl_demo.sql`** 创建演示表
-3. 修改 `config/config.development.js` 中的数据库账号等
-4. 根目录 `npm run api` 启动后端（默认端口见 `config/config.js`）
-5. `npm run dev` 启动管理端，浏览器访问 webpack 提示的端口
-
 ## 菜单与演示页
 
 在 `sys_menu` 中增加一条菜单：`component` 填 **`demo/tpl_demo`**（与 `admin/src/router/component-map.js` 一致），分配权限后即可打开「演示数据」列表页。