# 快速启动

本节引导您完成 HEG 的获取、配置与启动，并验证与氦闪中台的连接。

# 一、前置准备

# 1.1 环境要求

项目	要求
Docker	20.10 及以上
出方向网络	能访问氦闪中台 WebSocket 端口（默认 `9602`）与网关端口（默认 `10000`）
数据源	您自己的 MySQL / Redis / MongoDB 已就绪，且 HEG 所在服务器可访问

# 1.2 在开发者后台准备应用信息

登录氦闪开发者平台 (opens new window)。
在 应用管理 中创建应用。
进入 应用配置 → 配置数据源信息，选择边缘网关模式（此模式无需填写数据源连接信息，也无需配置中台 IP 白名单）。
记录该应用的 APPID 与 应用密钥（secret-key），后续配置 HEG 时使用。

# 二、获取镜像

# 方式一：使用源码构建（推荐，便于定制与升级）

构建机需具备 JDK 17、Maven 3.6+、Docker 20.10+。

# 拉取源码
git clone https://gitee.com/hai-shan-tec/heg-verify.git
cd heg-verify
chmod +x heg.sh

# 一步完成：拉代码 + 打包 + 构建镜像 + 导出 tar 包
./heg.sh build

构建产物为 heg.tar（未压缩），镜像命名规则为 heg:<日期>01，例如 heg:2026091101。

heg.sh 支持的子命令：

命令	说明
`./heg.sh package`	仅拉取代码并 Maven 打包
`./heg.sh image`	仅构建镜像并导出 tar 包（需先打包）
`./heg.sh build`	一步完成打包、构建镜像与导出 tar
`./heg.sh clean`	清理构建产物
`./heg.sh`	显示帮助

在目标服务器上加载镜像：

docker load -i heg.tar
docker images | grep heg

提示：项目依赖私有 SDK，若在内网构建，请确保该依赖已安装到本地仓库或私服。

# 方式二：使用 Docker Compose（环境变量配置）

源码根目录已提供 docker-compose.yml 与 .env.example：

cp .env.example .env
# 编辑 .env，至少填写 HEG_APP_ID 与 HEG_SECRET_KEY，以及需要的数据源
docker compose up -d

# 三、配置

HEG 支持两种配置方式，任选其一。

# 3.1 环境变量（配合 docker compose）

复制 .env.example 为 .env 后按下表填写：

变量	必填	默认值	说明
`HEG_SERVER_PORT`	否	`9000`	宿主机映射端口（容器内固定 9000）
`HEG_WEBSOCKET_URL`	是	—	中台 HEG WebSocket 地址
`HEG_APP_ID`	是	—	应用 APPID
`HEG_SECRET_KEY`	是	—	应用密钥
`HEG_API_BASE_URL`	是	—	中台网关地址（HTTP 转发使用）
`HEG_MYSQL_URL`	按需	空	MySQL 连接 URL，留空则不启用该数据源
`HEG_MYSQL_USERNAME` / `HEG_MYSQL_PASSWORD`	按需	`root` / 空	MySQL 账号密码
`HEG_MYSQL_INITIAL_SIZE` / `HEG_MYSQL_MAX_ACTIVE`	否	`5` / `20`	MySQL 连接池参数
`HEG_REDIS_HOST`	按需	空	Redis 地址，留空则不启用该数据源
`HEG_REDIS_PORT` / `HEG_REDIS_PASSWORD` / `HEG_REDIS_DATABASE`	否	`6379` / 空 / `0`	Redis 连接参数
`HEG_MONGO_URI`	按需	空	MongoDB 连接串，留空则不启用该数据源
`HEG_MONGO_DATABASE`	按需	空	MongoDB 数据库名
`HEG_MYSQL_APP_ID` / `HEG_REDIS_APP_ID` / `HEG_MONGO_APP_ID`	否	取 `HEG_APP_ID`	数据源归属应用，留空自动复用 `HEG_APP_ID`
`JAVA_OPTS`	否	`-Xms256m -Xmx512m -XX:+UseG1GC`	JVM 参数

重要：数据源的 APP_ID 必须与 HEG_APP_ID 完全一致（大小写敏感），否则该数据源不会生效。

# 3.2 外部配置文件（挂载 application.yml）

以源码中的 src/main/resources/application.yml 为模板，另存为宿主机配置文件后按实际环境填写：

mkdir -p /opt/heg/config /opt/heg/logs
vi /opt/heg/config/application.yml

该文件必须挂载（见第四节）才会生效；未挂载时程序使用镜像内置的默认配置。挂载后，文件中填写的值会覆盖镜像内置默认值中的对应项，未填写的键继承默认值。

配置内容示例（必改项已标注）：

server:
  port: 9000

heg:
  cloud:
    # 【必改】氦闪中台 HEG WebSocket 地址
    websocket-url: ws://<氦闪中台地址>:9602/heg
    # 【必改】应用 APPID
    app-id: <您的APPID>
    # 【必改】应用密钥
    secret-key: <您的SecretKey>
    # 【必改】氦闪中台网关地址
    api-base-url: http://<氦闪中台网关地址>:10000

  # 【必改】本地数据源（app-id 必须与上方 app-id 一致）
  mysql:
    - app-id: <您的APPID>
      url: jdbc:mysql://host.docker.internal:3306/<数据库名>?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
      username: <数据库用户名>
      password: <数据库密码>
      initial-size: 5
      max-active: 20

  redis:
    - app-id: <您的APPID>
      host: host.docker.internal
      port: 6379
      password:
      database: 0

  mongodb:
    - app-id: <您的APPID>
      uri: mongodb://<用户名>:<密码>@host.docker.internal:27017/admin
      database: <数据库名>

  app-log:
    path: /app/logs
    level: INFO
    retain-days: 30

注意：容器内的 localhost 指容器自身，不是宿主机。数据库在宿主机上时请使用 host.docker.internal（启动命令需带 --add-host）；数据库在其它服务器时直接填该服务器内网 IP。

# 四、启动容器

docker run -d \
  --name heg-verify \
  --restart always \
  -p 9000:9000 \
  -v /opt/heg/config/application.yml:/app/config/application.yml \
  -v /opt/heg/logs:/app/logs \
  --add-host=host.docker.internal:host-gateway \
  heg:2026091101

参数	说明
`-p 9000:9000`	宿主机端口:容器端口，9000 被占用可改为 `-p 9001:9000`
`-v .../application.yml:/app/config/application.yml`	挂载外部配置，覆盖镜像内置默认值
`-v /opt/heg/logs:/app/logs`	挂载日志目录，便于在宿主机查看
`--add-host=host.docker.internal:host-gateway`	允许容器内通过 `host.docker.internal` 访问宿主机

Windows：PowerShell 中换行符为反引号，或把命令写成一行；挂载路径改为 -v D:\heg\config\application.yml:/app/config/application.yml。

# 五、验证部署

# ① 容器状态
docker ps | grep heg-verify

# ② 启动日志（关键）
docker logs -f heg-verify

# ③ 健康检查
curl http://127.0.0.1:9000/heg/test/health

日志中出现以下内容表示连接成功：

========== HEG验证项目启动完成 ==========
MySQL连接池初始化成功: appId=您的APPID
HEG连接云端: ws://.../heg?appId=xxx&amp;token=xxx
WebSocket握手完成
连接成功: ws://.../heg?appId=xxx&amp;token=xxx

健康检查返回：

{"status":"UP","service":"HEG-Verify"}

最后登录氦闪开发者平台，在对应应用下查看 HEG 连接状态应为 已连接。

# 六、日常运维

docker logs --tail 200 heg-verify           # 查看最近 200 行日志
docker restart heg-verify                   # 修改外部配置后重启生效
docker stop heg-verify && docker rm heg-verify   # 停止并删除容器（镜像保留）
docker inspect heg-verify | grep -A 10 Mounts    # 查看挂载信息

升级：加载新镜像 → 删除旧容器（保留配置）→ 用新镜像 tag 重新启动。回滚：用旧镜像 tag 重新启动容器即可（旧镜像不要删除）。

# 七、常见问题

Q1：日志报「WebSocket 连接失败」

确认 websocket-url、app-id、secret-key 与开发者平台一致；
测试连通性：telnet <中台地址> 9602；
确认服务器出方向防火墙/安全组已放通 9602。

断开后会自动重连（1s→2s→4s…最长 60s），网络恢复后无需人工干预。

Q2：日志报「未配置 MySQL 数据源 / 连接池初始化失败」

检查数据源 app-id 与 cloud.app-id 完全一致；
数据库地址不能写 localhost，需用 host.docker.internal 或内网 IP；
测试连通性：docker run --rm --network container:heg-verify busybox nc -zv <数据库IP> 3306。

Q3：端口 9000 被占用：-p 改为其它宿主机端口，例如 -p 9001:9000（容器内仍为 9000）。

Q4：调整 JVM 内存：docker run ... -e JAVA_OPTS="-Xms512m -Xmx1024m" heg:2026091101。

Q5：修改配置后不生效：配置通过挂载加载，需 docker restart heg-verify，并用 docker inspect 确认挂载路径正确。

Q6：容器时间不对：可挂载宿主机时区文件修正：-v /etc/localtime:/etc/localtime:ro。

← HEG 网关概述持久化配置 →