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` 一致），分配权限后即可打开「演示数据」列表页。

config/config.development.js

@@ -1,21 +1,25 @@
 /**
- * 本地开发配置（请按实际环境修改数据库等）
+ * 本地开发配置
+ *
+ * 第一步：按本机 MySQL 修改下方 db（尤其 password）；库名需与 sql/init.sql 执行前 USE 的库一致。
+ * 可用环境变量覆盖：DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME（未设置则用下方默认值）。
  */
 
 module.exports = {
   db: {
-    username: "root",
+    username: process.env.DB_USER || "framework_project_web",
-    password: "your_password",
+    password: process.env.DB_PASSWORD || "6EiMpcJW63db5DTY",
-    database: "fullstack_template",
+    database: process.env.DB_NAME || "framework_project_web",
-    host: "127.0.0.1",
+    host: process.env.DB_HOST || "101.132.75.138",
-    port: 3306,
+    port: Number(process.env.DB_PORT) || 3306,
     dialect: "mysql",
   },
+  // 非空占位即可通过 oss 模块加载；真用 OSS 上传请改为控制台密钥与 bucket
   aliyun: {
-    accessKeyId: "",
+    accessKeyId: process.env.ALIYUN_ACCESS_KEY_ID || "local-dev-placeholder",
-    accessKeySecret: "",
+    accessKeySecret: process.env.ALIYUN_ACCESS_KEY_SECRET || "local-dev-placeholder",
-    ossUrl: "",
+    ossUrl: process.env.ALIYUN_OSS_URL || "",
-    bucket: "",
+    bucket: process.env.ALIYUN_OSS_BUCKET || "local-dev-placeholder",
   },
   redis: null,
 };

migrations/init.sql

@@ -1,127 +0,0 @@
--- 与 sql/init.sql 同步（内容一致）
--- =============================================================================
--- 前后端项目模板 · 初始化库表与基础数据（MySQL 5.7+ / 8.x，utf8mb4）
--- 执行前请创建空库并 USE 到目标 database；会 DROP 后重建系统表，请勿在生产库直接全量执行。
--- 默认管理员：admin / 123456（密码为 MD5 小写十六进制，与 node_core tokenService.getMd5 一致）
--- =============================================================================
-
-SET NAMES utf8mb4;
-SET FOREIGN_KEY_CHECKS = 0;
-
-DROP TABLE IF EXISTS `sys_log`;
-DROP TABLE IF EXISTS `sys_user`;
-DROP TABLE IF EXISTS `sys_menu`;
-DROP TABLE IF EXISTS `sys_role`;
-DROP TABLE IF EXISTS `sys_parameter`;
-DROP TABLE IF EXISTS `sys_tenant`;
-
-CREATE TABLE `sys_tenant` (
-  `id` int NOT NULL AUTO_INCREMENT,
-  `name` varchar(100) NOT NULL DEFAULT '' COMMENT '租户名称',
-  `code` varchar(64) NOT NULL DEFAULT '' COMMENT '租户编码（登录 tenant_code）',
-  `remark` varchar(255) NOT NULL DEFAULT '' COMMENT '备注',
-  `status` int NOT NULL DEFAULT 1 COMMENT '1启用 0停用',
-  `is_platform` int NOT NULL DEFAULT 0 COMMENT '1平台租户',
-  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `last_modify_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  `is_delete` int NOT NULL DEFAULT 0,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `uk_sys_tenant_code` (`code`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='租户';
-
-CREATE TABLE `sys_role` (
-  `id` int NOT NULL AUTO_INCREMENT,
-  `name` varchar(100) NOT NULL DEFAULT '' COMMENT '角色名称',
-  `type` int NOT NULL DEFAULT 0 COMMENT '0普通 1系统',
-  `menus` json DEFAULT NULL COMMENT '权限菜单id数组等',
-  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `last_modify_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  `is_delete` int NOT NULL DEFAULT 0,
-  PRIMARY KEY (`id`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='角色';
-
-CREATE TABLE `sys_user` (
-  `id` int NOT NULL AUTO_INCREMENT,
-  `name` varchar(100) NOT NULL DEFAULT '' COMMENT '登录名',
-  `password` varchar(100) NOT NULL DEFAULT '' COMMENT 'MD5密码',
-  `roleId` int NOT NULL COMMENT '角色id',
-  `tenant_id` int NOT NULL DEFAULT 1 COMMENT '租户id',
-  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `last_modify_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  `is_delete` int NOT NULL DEFAULT 0,
-  PRIMARY KEY (`id`),
-  KEY `idx_sys_user_tenant` (`tenant_id`),
-  KEY `idx_sys_user_role` (`roleId`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户';
-
-CREATE TABLE `sys_menu` (
-  `id` int NOT NULL AUTO_INCREMENT,
-  `name` varchar(100) NOT NULL DEFAULT '' COMMENT '菜单名称',
-  `parent_id` int unsigned DEFAULT 0 COMMENT '父id',
-  `icon` varchar(100) NOT NULL DEFAULT '' COMMENT '图标',
-  `path` varchar(255) NOT NULL DEFAULT '' COMMENT '路径',
-  `type` varchar(255) NOT NULL DEFAULT '页面' COMMENT '菜单/页面/外链/功能',
-  `model_id` int unsigned DEFAULT 0 COMMENT '模型id',
-  `form_id` int unsigned DEFAULT 0 COMMENT '表单id',
-  `component` varchar(100) NOT NULL DEFAULT '' COMMENT '组件地址',
-  `api_path` varchar(100) NOT NULL DEFAULT '' COMMENT 'api地址',
-  `is_show_menu` int NOT NULL DEFAULT 1 COMMENT '是否显示在菜单',
-  `is_show` int NOT NULL DEFAULT 1 COMMENT '是否展示',
-  `sort` int NOT NULL DEFAULT 0 COMMENT '排序',
-  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `last_modify_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  `is_delete` int NOT NULL DEFAULT 0,
-  PRIMARY KEY (`id`),
-  KEY `idx_sys_menu_parent` (`parent_id`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='菜单';
-
-CREATE TABLE `sys_parameter` (
-  `id` int NOT NULL AUTO_INCREMENT,
-  `key` varchar(100) NOT NULL DEFAULT '' COMMENT '参数key',
-  `value` varchar(500) NOT NULL DEFAULT '' COMMENT '值',
-  `remark` varchar(500) NOT NULL DEFAULT '' COMMENT '备注',
-  `is_modified` int NOT NULL DEFAULT 0 COMMENT '0允许修改 1不允许',
-  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `last_modify_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  `is_delete` int NOT NULL DEFAULT 0,
-  PRIMARY KEY (`id`),
-  UNIQUE KEY `uk_sys_parameter_key` (`key`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统参数';
-
-CREATE TABLE `sys_log` (
-  `id` int NOT NULL AUTO_INCREMENT,
-  `table_name` varchar(100) NOT NULL DEFAULT '' COMMENT '表名',
-  `operate` varchar(100) NOT NULL DEFAULT '' COMMENT '操作',
-  `content` json DEFAULT NULL COMMENT '内容',
-  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  `last_modify_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-  `is_delete` int NOT NULL DEFAULT 0,
-  PRIMARY KEY (`id`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='操作日志';
-
-SET FOREIGN_KEY_CHECKS = 1;
-
-INSERT INTO `sys_tenant` (`id`, `name`, `code`, `remark`, `status`, `is_platform`, `is_delete`)
-VALUES (1, '默认平台租户', 'default', '初始化数据', 1, 1, 0);
-
-INSERT INTO `sys_role` (`id`, `name`, `type`, `menus`, `is_delete`)
-VALUES (1, '超级管理员', 1, CAST('[]' AS JSON), 0);
-
-INSERT INTO `sys_user` (`id`, `name`, `password`, `roleId`, `tenant_id`, `is_delete`)
-VALUES (1, 'admin', 'e10adc3949ba59abbe56e057f20f883e', 1, 1, 0);
-
-INSERT INTO `sys_parameter` (`key`, `value`, `remark`, `is_modified`, `is_delete`) VALUES
-('sys_title', '管理系统', '登录页与顶栏标题', 0, 0),
-('sys_logo', '', '顶栏 Logo 图片地址，可填上传后的相对路径', 0, 0);
-
-INSERT INTO `sys_menu` (`id`, `name`, `parent_id`, `icon`, `path`, `type`, `model_id`, `form_id`, `component`, `api_path`, `is_show_menu`, `is_show`, `sort`, `is_delete`) VALUES
-(1, '首页', 0, 'md-home', '/home', '页面', 0, 0, 'home/index', '', 1, 1, 1, 0),
-(5, '系统管理', 0, 'md-settings', '/system', '菜单', 0, 0, '', '', 1, 1, 2, 0),
-(11, '用户管理', 5, 'md-person', '/system/user', '页面', 0, 0, 'system/sys_user', '', 1, 1, 1, 0),
-(12, '角色管理', 5, 'md-people', '/system/role', '页面', 0, 0, 'system/sys_role', '', 1, 1, 2, 0),
-(13, '系统日志', 5, 'md-list', '/system/log', '页面', 0, 0, 'system/sys_log', '', 1, 1, 3, 0),
-(15, '参数设置', 5, 'md-options', '/system/param', '页面', 0, 0, 'system/sys_param_setup', '', 1, 1, 4, 0),
-(120, '高级管理', 0, 'md-construct', '/system', '菜单', 0, 0, '', '', 1, 1, 3, 0),
-(122, '菜单管理', 120, 'md-menu', '/system/menu', '页面', 0, 0, 'system/sys_menu', '', 1, 1, 1, 0),
-(124, '系统标题', 120, 'md-text', '/system/title', '页面', 0, 0, 'system/sys_title', '', 1, 1, 2, 0),
-(125, '租户管理', 120, 'md-git-branch', '/system/tenant', '页面', 0, 0, 'system/sys_tenant', '', 1, 1, 3, 0);

sql/init.sql

@@ -1,6 +1,7 @@
+-- Active: 1775110656953@@101.132.75.138@3306@framework_project_web
 -- =============================================================================
 -- 前后端项目模板 · 初始化库表与基础数据（MySQL 5.7+ / 8.x，utf8mb4）
--- 执行前请创建空库并 USE 到目标 database；会 DROP 后重建系统表，请勿在生产库直接全量执行。
+-- 执行前请创建空库并 USE 到目标 database（库名须与 config/config.development.js 里 db.database 一致）；会 DROP 后重建系统表，请勿在生产库直接全量执行。
 -- 默认管理员：admin / 123456（密码为 MD5 小写十六进制，与 node_core tokenService.getMd5 一致）
 -- =============================================================================