135 lines
8.7 KiB
Markdown
135 lines
8.7 KiB
Markdown
# 系统管理后台本地部署
|
||
|
||
实施日期：2026-10-05。项目目录：`C:\Users\Administrator\Desktop\projects\elder-yudao-pro`，分支：`axr`。
|
||
|
||
本阶段运行现有芋道系统管理后台，包括用户、角色、菜单、部门、字典等功能。服务由 `yudao-server` 承载，依赖已启用的 `yudao-module-system` 和 `yudao-module-infra`；其他业务模块暂未启用，老年健康业务尚未迁移。本次部署在本机运行。
|
||
|
||
## 当前访问方式
|
||
|
||
| 内容 | 地址或配置 |
|
||
| --- | --- |
|
||
| Vue 3 管理界面 | http://127.0.0.1:5173 |
|
||
| 后端接口文档 | http://127.0.0.1:48080/doc.html |
|
||
| 健康检查 | http://127.0.0.1:48080/actuator/health |
|
||
| 登录租户 | 管理端默认使用 `tenant-id: 1`，无需填写原模板租户名 |
|
||
| 初始化管理员 | `admin` / `admin123` |
|
||
| MySQL 独立数据库 | 本机 macOS：`elder_yudao_local`，`127.0.0.1:3307`；其他机器以根目录 `.env` 或 Windows 配置为准 |
|
||
| Redis | `127.0.0.1:6379`，15 号库 |
|
||
|
||
前后端只监听 `127.0.0.1`。启动的是本地开发环境，验证码关闭、模拟登录关闭、Quartz 暂停，Actuator 只开放 `health` 和 `info`，Druid 控制台关闭。
|
||
|
||
## 本机 IDEA 数据库连接（2026-10-08）
|
||
|
||
本机有两个 MySQL 实例，3306 属于原有 `/usr/local/mysql`，本项目使用 Homebrew 实例的 3307。
|
||
IDEA 中填写主机 `127.0.0.1`、端口 `3307`、用户 `root`、数据库 `elder_yudao_local`；密码取根目录 `.env` 的 `ELDER_DB_PASSWORD`。
|
||
连接 URL 为 `jdbc:mysql://127.0.0.1:3307/elder_yudao_local`。IDEA 不会自动读取项目 `.env` 更新数据源密码。
|
||
项目 MySQL 的用户启动项已固定端口 3307、仅监听本机，并使用 `/tmp/elder-mysql.sock`，避免和另一实例争用端口或套接字。
|
||
|
||
## 环境与本次修复
|
||
|
||
- 本机使用 Java 11.0.12、Maven 3.9.12、MySQL 8.0.44 和现有 Redis 服务。源码目标版本仍为 Java 8，Spring Boot 仍为 2.7.18。
|
||
- 补回根目录 `lombok.config`。模板调用链式 setter，需要 `lombok.accessors.chain=true`；缺失时 `ApiAccessLogFilter` 等源码无法编译。
|
||
- 新增 `application-desktop.yaml`，叠加在 `local` 配置之后。数据库连接、日志路径和端口通过环境变量传入。
|
||
- 私有连接配置位于 `deploy/local/secrets.psd1`，已加入 Git 忽略规则。当前使用本机已有的数据库连接信息，不在本文记录数据库密码。
|
||
- 初始化脚本只允许 `elder_yudao_*` 独立库，且拒绝向非空库重复导入。种子文件为 `mysql_script/ruoyi-vue-pro.sql`，已导入 61 张表，默认文件存储改为数据库存储。
|
||
|
||
现有 MySQL 服务内其他数据库和 Redis 0 号库未清空或导入数据。
|
||
|
||
## 后续启动与停止
|
||
|
||
在项目根目录打开 PowerShell。
|
||
|
||
启动后端、检查登录和基础接口、启动界面：
|
||
|
||
```powershell
|
||
.\deploy\local\start.ps1
|
||
.\deploy\local\check.ps1
|
||
.\deploy\local\start-ui.ps1
|
||
```
|
||
|
||
后端启动通常需要约 30 秒。健康检查返回 `UP` 后访问管理界面。若刚修改后端源码或配置，先停止服务，再重新构建启动：
|
||
|
||
```powershell
|
||
.\deploy\local\stop.ps1
|
||
.\deploy\local\start.ps1 -Build
|
||
```
|
||
|
||
分别停止界面和后端：
|
||
|
||
```powershell
|
||
.\deploy\local\stop-ui.ps1
|
||
.\deploy\local\stop.ps1
|
||
```
|
||
|
||
脚本通过记录的 PID 和对应程序路径核对进程，避免停止其他 Java 或 Node 项目。它们启动隐藏的后台进程，不修改系统服务。
|
||
|
||
日志和 PID 位于 `deploy/local/.runtime/`，已加入 Git 忽略规则：
|
||
|
||
- `application.log`、`stdout.log`、`stderr.log`：后端日志。
|
||
- `ui-stdout.log`、`ui-stderr.log`：界面日志。
|
||
- `server.pid`、`ui.pid`：运行中的进程编号。
|
||
- `ui-src/`：历史管理界面缓存；当前维护和启动目录为仓库根目录的 `yudao-ui-admin-vue3/`。
|
||
|
||
## 在另一台电脑初始化
|
||
|
||
先安装 Java 8/11、Maven、MySQL 8、Redis，以及 Node.js（界面依赖要求 Node 18+，本机验证为 Node 24.12.0）。启动 MySQL 和 Redis。
|
||
|
||
```powershell
|
||
Copy-Item .\deploy\local\secrets.example.psd1 .\deploy\local\secrets.psd1
|
||
```
|
||
|
||
编辑 `secrets.psd1`，填写数据库密码；如程序不在 PATH 中，可填写 `JavaExe`、`MySqlExe`。确认数据库名为新建独立库、Redis 库编号没有被其他项目使用。
|
||
|
||
以下初始化命令仅在首次运行时执行。已有表时脚本会停止，不会覆盖：
|
||
|
||
```powershell
|
||
.\deploy\local\initialize.ps1
|
||
.\deploy\local\start.ps1 -Build
|
||
.\deploy\local\prepare-ui.ps1
|
||
.\deploy\local\start-ui.ps1
|
||
```
|
||
|
||
`check.ps1` 使用种子管理员密码做检查；修改管理员密码后，应相应调整检查方式。
|
||
|
||
## 在 IDEA 中运行后端
|
||
|
||
在项目根目录的 PowerShell 终端执行：
|
||
|
||
```powershell
|
||
.\deploy\local\prepare-idea.ps1
|
||
```
|
||
|
||
在 IDEA 右上角选择 `ElderYudao Local` 运行配置，点击运行；若没有出现，重新打开 `elder-yudao-pro` 项目。启动类为 `cn.iocoder.yudao.server.YudaoServerApplication`，模块为 `yudao-server`，激活环境为 `local,desktop`。
|
||
|
||
该脚本从 `secrets.psd1` 读取本地连接参数，生成 `.run/ElderYudaoLocal.run.xml`。此文件包含数据库密码，已加入 Git 忽略规则。修改连接参数后重新执行脚本即可。脚本只生成配置，不启动进程。
|
||
|
||
也可以继续使用原来的 `YudaoServerApplication` 运行配置。`application.yaml` 默认激活 `local`；`application-local.yaml` 的主数据库已改为 `elder_yudao_local`，从数据库名称跟随主库。此方式使用 `application-local.yaml` 中的连接账号与密码，本机当前配置已验证能读取该库的租户表。
|
||
|
||
`ElderYudao Local` 启动项仍使用 `local,desktop`，通过私有运行配置传入连接参数，同时应用仅监听本机、使用 Redis 15 号库等部署设置。若手动启用 `desktop`，需要设置环境变量 `ELDER_DB_PASSWORD`，其值为 `secrets.psd1` 中的 `DatabasePassword`。
|
||
|
||
若日志出现 `Table 'ruoyi-vue-pro.system_tenant' doesn't exist` 或 `Table 'ruoyi-vue-pro.infra_api_error_log' doesn't exist`，说明当前进程仍指向模板原来的数据库。停止后端，在 IDEA 重新构建并启动，再刷新前端；实际应连接已初始化的 `elder_yudao_local`。不要为这两张表单独生成 DDL，系统需要的是完整的初始化数据。
|
||
|
||
## 在 IDEA 中运行前端
|
||
|
||
项目内已保存 `.run/ElderYudaoFrontend.run.xml`。在 IDEA 顶部运行配置列表选择 `ElderYudao Frontend`，点击运行按钮即可启动前端；点击停止按钮结束它。页面地址为 http://127.0.0.1:5173 。如果运行配置暂未出现，重新打开项目。
|
||
|
||
该配置使用 Node.js 运行 Vite，工作目录和脚本位置均相对于项目根目录，参数为 `--mode desktop --host 127.0.0.1 --port 5173 --strictPort`，与已验证的终端启动命令一致。Node.js 当前路径为 `E:/BiSh/NodeJS/node.exe`；换电脑后，可在 Edit Configurations 中选择对应的 Node interpreter。前端源码与 `.env.desktop` 已在 `yudao-ui-admin-vue3/` 中；若尚未准备依赖，先执行 `prepare-ui.ps1`。
|
||
|
||
前端运行日志会显示在 IDEA 的 Run 窗口中。正常登录还需要后端 `ElderYudao Local` 同时运行。
|
||
|
||
## 管理界面来源与依赖固定
|
||
|
||
此后端仓库原本没有管理界面源码。本次使用 [yudao-ui-admin-vue3](https://github.com/yudaocode/yudao-ui-admin-vue3/tree/v2.0.1) 的 `v2.0.1` 标签，对应提交 `6f38676af78349a79b5428bca082ea0d8b4f3142`。源码现已纳入 `yudao-ui-admin-vue3/`，并参考 Olive 管理端完成界面定制。`prepare-ui.ps1` 使用 `pnpm 8.6.12` 和该目录的 `pnpm-lock.yaml` 安装固定依赖，不再克隆或覆盖源码。
|
||
|
||
SWC 固定为 `1.4.14`。未固定时，旧版前端依赖解析到了 `1.16.13`，在本机触发 `ERR_SWC_NATIVE_CACHE`，导致 Vite 无法启动；固定后界面验证通过。前端 `.env.desktop` 已提供默认本机配置，`start-ui.ps1` 也可按部署配置生成，调用本机的 `/admin-api`，关闭验证码和外部统计。
|
||
|
||
这是 Vite 开发服务，用于当前本地验证；生产服务器、域名、HTTPS 和持续运行服务尚未部署。界面源码现已作为 `yudao-ui-admin-vue3/` 纳入版本管理，后续页面迁移在该目录进行。参考 [管理端界面定制](管理端界面定制.md)。
|
||
|
||
## 已验证结果
|
||
|
||
- Maven 构建：24 个参与构建的模块全部成功；打包时跳过现有单元测试，未声称执行完整测试套件。
|
||
- MySQL 初始化：61 张表，租户 1 的管理员存在；重复初始化会拒绝非空库。
|
||
- 健康检查：`UP`；接口文档：HTTP 200。
|
||
- 登录、权限信息、用户分页、退出接口：业务状态码均为 0，用户分页返回 9 条记录。
|
||
- 浏览器：登录后进入 `/index`，打开 `/system/user` 显示用户管理页面和 9 行数据，无页面脚本错误、无接口 HTTP 错误。
|