bj_power/bj_power_mes/打包部署.md

打包部署

本文档同时面向 AI 助手（约束和规则）和 运维人员（操作步骤）。

---

一、AI 约束（必读）

1.1 打包环境

• 构建机：macOS（Go 交叉编译到 Windows）
• 目标平台：Windows amd64

1.2 构建命令

# 前端构建 + 交叉编译 + 复制资源文件，输出到 bin/
bash build-windows.sh

1.3 编译参数硬约束

参数	值	原因
CGO_ENABLED	0	纯 Go 项目，禁用 CGO 才能跨平台编译
GOOS	windows	目标平台
GOARCH	amd64	64 位
-ldflags	-s -w -H=windowsgui	去除调试信息 + 隐藏命令行窗口
-trimpath	必须	去除源码路径信息

1.4 构建前置条件

1. ent/ 代码已生成：ent/ 目录在 .gitignore 中，不提交 git。若 ent/ 不存在，需先执行 go generate ./schema/...
2. 前端已构建：脚本会自动执行 npm run build，但需确保 node_modules 已安装
3. Go 版本：go.mod 中 go 1.25.0

1.5 数据库工具编译规则

• schema/tools/migrate.go — 编译为 migrate.exe，必须同时编译 app.go：go build migrate.go app.go
• schema/tools/data.go — 编译为 data.exe，必须同时编译 app.go：go build data.go app.go
• 两个文件都有 //go:build ignore，不可单独编译，必须显式指定文件列表
• app.go 提供 getAppDir() 和 loadDBConfig() 公共函数

1.6 输出目录

• 输出到 bin/（与 build.bat 保持一致，.gitignore 中已忽略）
• 目录结构：

bin/
├── spherical.exe          # 主程序（GUI 模式，隐藏控制台）
├── migrate.exe            # 数据库表结构迁移
├── data.exe               # 数据初始化（signals/seed/admin）
├── app.ico                # 托盘图标
├── etc/
│   └── spherical-api.yaml # 配置文件
└── doc/
    ├── signals.sql        # PLC 信号定义（146 条）
    ├── data.sql           # 设备/配方/产品种子数据
    ├── reset.sql          # 生产数据重置脚本
    ├── engine_schema.sql  # 新引擎表结构（recipe_step_resource 等）
    └── new_recipe.sql     # 新引擎配方种子数据

1.7 禁止事项

• 禁止修改 build-windows.sh 中的 CGO_ENABLED=0、GOOS=windows、-H=windowsgui
• 禁止在 bin/ 目录中放入 go.mod、go.sum、源码文件
• 禁止将 public/ 打包到 bin/（前端已通过 //go:embed public 嵌入 exe）
• 数据库工具 data.go 和 migrate.go 的路由定位依赖 getAppDir()（基于 exe 路径），不要改为基于 go.mod 的定位方式

---

二、技术栈版本

组件	版本	说明
Go	1.25.0	go.mod
pgx	v5.7.4	PostgreSQL 驱动，支持 PG 12-17
PostgreSQL	17（推荐）	兼容 12-17
Node.js	18+	前端构建
Vite	7.x	前端构建工具
React	18.x	前端框架
ent	0.14.x	ORM

---

三、Windows 部署步骤（给人看）

3.1 环境准备

1. 安装 PostgreSQL 17：下载
   • 安装时设置超级用户密码，端口保持默认 5432
2. 安装 Node.js 18+（如果需要在 Windows 上重新构建前端）

3.2 部署文件

将 bin/ 整个目录复制到 Windows 电脑，例如 D:\spherical\

3.3 修改配置

编辑 etc/spherical-api.yaml，修改数据库密码：

Database:
  Host: 127.0.0.1
  Port: 5432
  User: postgres
  Password: 你的密码    # ← 必须修改
  Dbname: spherical

3.4 创建数据库

用 pgAdmin 或 psql 执行：

CREATE DATABASE spherical;

3.5 初始化数据库

打开 命令提示符（cmd），进入部署目录，依次执行：

cd D:\spherical

# 1. 创建表结构（根据 ent schema 自动建表）
migrate.exe

# 2. 导入 PLC 信号定义（146 条）
data.exe signals

# 3. 导入设备/配方/产品种子数据
data.exe seed

# 4. 创建管理员账号
data.exe admin

# 5. 初始化新引擎（创建引擎表结构 + 导入配方种子数据）
#    交互式命令，输入 y 确认
data.exe new-engine

重要： 步骤 5 必须执行。新引擎依赖 recipe_step_resource/signal/action/decision、resource_lock、job_step 等表与配方数据，缺少会导致产线无法运行（引擎找不到配方/资源）。

数据库工具命令一览

所有 data.exe 支持的命令（在 cmd 中运行）：

命令	说明	是否交互
data.exe signals	导入 PLC 信号定义到 signal 表	否
data.exe seed	导入设备类型、设备实例、槽位、配方、产品类型	否
data.exe admin	创建默认管理员账号 admin/admin123	否
data.exe reset-pwd	重置 admin 密码为 admin123	否
data.exe reset	清空所有生产数据，恢复设备槽位为空闲	是（需输入 y 确认）
data.exe reset-all	完全重建数据库：删表 → 建表 → 导入种子数据 + 管理员 + 信号 + 迁移（含新引擎表结构）	是（需输入 y 确认）
data.exe migrate	执行数据库结构迁移（幂等，列不存在时跳过）	是（需输入 y 确认）
data.exe new-engine	初始化新引擎：创建引擎表结构 + 导入配方数据（已有数据库升级用，reset-all 已包含）	是（需输入 y 确认）

支持一次执行多个命令：

data.exe seed admin signals    # 依次执行 seed、admin、signals

migrate.exe 说明

migrate.exe 等价于 data.exe migrate，用于数据库表结构迁移。首次部署时使用 migrate.exe 创建所有表结构，后续 schema 变更后使用 data.exe migrate 执行增量迁移。

注意： data.exe 和 migrate.exe 是控制台程序，必须从 命令提示符（cmd） 运行，不要双击执行（窗口会一闪而过）。交互式命令（如 reset-all）运行后会提示输入 y 确认，输入后按回车继续。

3.6 启动系统

spherical.exe

• 首次运行自动创建桌面快捷方式「华德零件自动化生产线管控系统」
• 程序在系统托盘运行，右键托盘图标可打开页面 / 设置开机启动 / 退出
• 浏览器自动打开 http://127.0.0.1:8888

3.7 登录

用户名	密码
admin	admin123

3.8 数据重置

方式一：完全重建（推荐用于 schema 变更后）

清空数据库并重新导入所有数据：

data.exe reset-all

运行后会提示「警告：此操作将删除所有表并重建数据库！所有数据将永久丢失！输入 y 继续:」，输入 y 回车确认。

reset-all 已包含新引擎初始化（new-engine 的全部内容），重建后即可直接运行 mockrun/产线，无需再单独执行 data.exe new-engine。

方式二：仅清空生产数据

保留基础配置（设备、产品、配方、PLC 信号、用户），仅清空工单、工件、事件日志等生产数据：

data.exe reset

方式三：手动执行 SQL

psql -U postgres -d spherical -f doc/reset.sql
data.exe seed

其他维护命令

data.exe reset-pwd    # 重置 admin 密码为 admin123
data.exe migrate      # 执行数据库结构增量迁移

---

四、常见问题

问题	解决
运行 exe 提示缺少 DLL	安装 Visual C++ Redistributable
数据库连接失败	检查 etc/spherical-api.yaml 中密码是否正确，PostgreSQL 服务是否启动
端口被占用	修改 etc/spherical-api.yaml 中 Port 字段
快捷方式没出现	检查 PowerShell 执行策略：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
开机启动不生效	以管理员身份运行一次，在托盘菜单中重新勾选
data.exe 或 migrate.exe 双击一闪而过	这是控制台程序，必须从 命令提示符（cmd） 运行，不要双击
data.exe reset-all 无响应	程序在等待输入 y 确认，看清提示后输入 y 回车。如果仍然无响应，检查 etc/spherical-api.yaml 中数据库配置是否正确
数据库工具连接失败	工具从 etc/spherical-api.yaml 读取数据库配置，路径基于 exe 所在目录。确保 etc/ 目录与 data.exe 在同一级