# 商用设备维保巡检 1.0.0 · 安装部署手册

本手册以本产品实际配置为准。Java编译目标17，Docker使用JDK21/Maven3.9构建、JRE21运行；前端Docker使用Node24/pnpm11.1.3；数据服务为MySQL8.4、Redis7.4。详细版本见技术架构与目录说明（源码包内：`docs/技术架构与目录说明.md`）。容量需按同时运行的产品、数据、附件、日志和备份估算；共享服务器使用独立资源配置，不直接套用单产品容量。

## 1. 新装正式环境

准备Linux、Docker Engine与Compose插件、OpenSSL。解压源码到独立目录，数据库与Redis不直接暴露公网。

```sh
cd deploy
./scripts/init-env.sh
# 编辑.env中的端口、管理员初始密码等；不要公开或提交.env
docker compose config --quiet
docker compose up -d --build
docker compose ps
```

init-env.sh生成随机数据库/Redis密码、令牌密钥及支付参数加密密钥，文件权限600；已存在.env时不覆盖。管理员初始密码通过ADMIN_INIT_PASSWORD设置，未设置时首次初始化日志会打印一次随机口令。首次登录必须改密；后续仅修改环境变量不会重置已有管理员密码。

正式安装保持APP_DEMO_DATA=false、APP_DEMO_RESET_ENABLED=false、APP_DEMO_RESET_CRON=-。首次启动Flyway自动执行db/base与db/app，创建基础表、业务表和菜单，不创建公开演示账号。管理后台为`/`，手机端为`/h5/`，同源API为`/api/`。

安装后先设置系统名称、公司与联系方式，再创建角色/业务用户并关联联系人或工程师档案，最后录入客户、项目、设备、合同、模板和计划。流程见[业务说明](business.md)。本产品合同金额只作资料记录，不接线上资金收付。

## 2. HTTPS与代理

推荐已有Caddy/Nginx统一终止HTTPS，容器只监听本机：在.env设置NGINX_CONF=proxy.conf、HTTP_BIND=127.0.0.1及未占用的HTTP_PORT。前置代理传递Host、客户端IP和X-Forwarded-Proto；Caddy示例：

```caddyfile
service.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8091
}
```

将示例域名替换为自己的已解析域名，HTTP_PORT与反向代理目标保持相同。外部用户访问HTTPS域名，不直接访问8091或容器端口。Nginx将/api/转发到server并去掉前缀，H5始终使用同源/api。

也可用docker-compose.https.yml让容器Nginx终止HTTPS：按该文件说明准备证书、设置COMPOSE_FILE及HTTPS端口。证书置于deploy/nginx/certs并单独保管，不放进源码包。不要同时让两套代理争用相同端口。

## 3. 当前演示目标与共享服务器配置

2026-10-23部署目标如下；本轮UI与文档改动完成不表示上线已经验收，最终状态以部署记录为准。

| 项目 | 配置 |
|---|---|
| 管理后台 | https://wb.diankit.com/ |
| 手机H5 | https://wb.diankit.com/h5/ |
| API | https://wb.diankit.com/api/ |
| 工程目录 | /opt/equipment-maintenance |
| Compose项目 | equipment-maintenance-demo |
| 容器Web映射 | 127.0.0.1:8091，由Caddy提供HTTPS |

演示.env使用COMPOSE_FILE=docker-compose.yml:docker-compose.demo-server.yml和COMPOSE_PROJECT_NAME=equipment-maintenance-demo，另设NGINX_CONF=proxy.conf、HTTP_BIND=127.0.0.1、HTTP_PORT=8091。资源与日志轮转由docker-compose.demo-server.yml叠加，所有docker compose命令自动使用两份配置。也可显式执行：

```sh
cd deploy
docker compose -p equipment-maintenance-demo -f docker-compose.yml -f docker-compose.demo-server.yml config --quiet
docker compose -p equipment-maintenance-demo -f docker-compose.yml -f docker-compose.demo-server.yml up -d --build
```

这里是特定演示目标，不是买家必须使用的域名、目录或端口。自己的安装应更换为自己的环境。真实账号、密码、DCloud密钥及证书不写进文档或交付ZIP。

## 4. 演示数据与恢复

全新演示环境在生成.env前执行`./scripts/init-env.sh --demo`；正式库不能事后当作演示库使用。公开普通演示用户见README，超级管理员没有公开默认密码。

业务恢复须同时开启APP_DEMO_DATA与APP_DEMO_RESET_ENABLED，仅真实user_id=1可在系统设置→演示维护执行。源码默认定时恢复关闭。当前专用演示目标由部署维护者设置每日北京时间04:11，即`0 11 4 * * *`；正式客户库禁止开启自动恢复。具体范围、备份和权限见演示数据恢复机制（源码包内：`docs/演示数据恢复机制.md`），不要用down -v重置业务。

## 5. 本机源码开发

准备JDK21、Maven3.9、Node24、pnpm11.1.3。以下开发依赖配置只绑定本机，包含公开开发值，不用于公网：

```sh
# 项目根目录；先确认端口未被其他工程占用
docker compose -f deploy/docker-compose.dev.yml up -d
cd server
mvn package
# 将ruoyi-admin/target/ruoyi-admin.jar复制到自己独立运行目录再启动
SPRING_PROFILES_ACTIVE=dev java -jar /您的独立运行目录/server.jar
```

dev配置使用MySQL13421、Redis16421、server18221及equipment_maintenance数据库。需要自有口令时，通过DB_URL/DB_USERNAME/DB_PASSWORD/REDIS_PASSWORD/TOKEN_SECRET/ADMIN_INIT_PASSWORD覆盖；不要修改正在运行实例的口令。另开终端，在项目根目录分别运行：

```sh
cd web
pnpm install --frozen-lockfile
pnpm dev --port 5191
```

```sh
cd client
pnpm install --frozen-lockfile
pnpm dev:h5 --port 5291
```

前端开发代理/api到18221，生产由Nginx转发。运行中的JAR必须与target分离，避免重新构建时覆盖正在运行的归档。

## 6. App与微信小程序

```sh
cd client
pnpm type-check
pnpm build:h5
VITE_API_BASE=https://您的域名/api pnpm build:app
VITE_API_BASE=https://您的域名/api pnpm build:mp-weixin
```

H5输出dist/build/h5；App运行资源输出dist/build/app。App名“设备维保巡检”，Android包名com.diankit.maintenance；需要为实际运营主体申请独立DCloud AppID/AppKey及签名证书。App资源编译成功不等于已生成或验收签名APK；不要用假标识，也不要复用其他产品密钥。微信需自己的AppID、HTTPS合法域名与隐私声明。

品牌SVG位于client/src/static/brand-mark.svg，Android各密度图标位于static/app并在manifest关联。更换品牌同时更新页面名称、图标、原生配置及真实协议。Android仅浏览/隐私状态未知时不恢复会话，原生同意后重启再加载相机和扫码能力。

局域网App测试可显式设置VITE_ALLOW_HTTP_API=1，如模拟器直连`http://10.0.2.2:18221`，没有/api前缀；正式App必须HTTPS。手机“我的→接口连接设置”可切换自有服务端并退出旧会话。真机不能用127.0.0.1访问电脑。

H5推荐同源/api；默认CSP connect-src为self。若H5确需跨域，须同时配置服务端精确CORS来源和H5 CSP目标，不能只在页面改URL。H5支持浏览器打印；App提供报告查看与复制摘要，未接原生打印硬件。签名上传图片不等同CA签章。

## 7. 备份、升级和恢复

```sh
cd deploy
./scripts/backup.sh
# 独立备份.env、加密密钥和证书后再更新源码
docker compose up -d --build
docker compose ps
```

backup.sh备份数据库与上传文件到deploy/backups的时间目录，目录700/文件600；.env、密钥和证书必须另存。需要回滚时先停写、核对目标库并再备份当前状态，再按restore.sh提示恢复；该脚本会覆盖目标库和上传文件，不能对错误项目运行。演示恢复卷只含白名单业务备份，不能替代完整灾备。

升级前保留上版源码/镜像及备份；Flyway只新增迁移，不能修改已执行脚本。不运行docker compose down -v作为常规维护，也不清空Redis或安全日志来“修复登录”。

## 8. 验证

```sh
cd server && mvn test
cd ../web && pnpm build && pnpm test
cd ../client && pnpm type-check && pnpm test && pnpm build:h5
```

历史执行结果见测试与交付记录（源码包内：`docs/测试与交付记录.md`）。部署后还需实际登录、角色隔离、照片上传、设备码、打印、备份以及网络失败验收。没有接入短信、IoT或真实支付，不能从编译成功推断这些外部能力可用。

## 2026-10-23 当前部署记录

本产品公开演示站已完成HTTPS、管理与H5资源、角色/系统设置/业务只读接口验收；本次管理员初始化与真实备份已核对。具体隔离参数、定时恢复与验证边界见[演示站部署验收记录](deployment-20261023.md)，原生包更新要求见[构建与后续更新要求](updates.md)。不把历史UI阶段记录视为当前最终交付状态。


---
官网公开文档：已移除内部维护段落。实际部署凭据不公开；未作为网页提供的包内文档以明确路径标注。APK与演示下载状态以产品页面为准。