# 持久化配置

HEG 涉及三类需要持久化的数据：运行时配置、应用运行日志、业务操作日志。它们分别由不同的配置项控制，且都位于容器内的 /app/data、/app/logs 两个目录，需要挂载才能落到宿主机。

# 一、配置项总览

配置项（application.yml）	环境变量	默认值	说明
`heg.config-persistence.type`	`HEG_CONFIG_PERSISTENCE_TYPE`	`file`	运行时配置存储方式：`memory` / `file`
`heg.config-persistence.file-path`	`HEG_CONFIG_FILE_PATH`	`/app/data/heg-runtime-config.yml`	配置持久化文件路径
`heg.app-log.path`	`HEG_LOG_PATH`	`/app/logs`	应用运行日志目录
`heg.app-log.level`	`HEG_LOG_LEVEL`	`INFO`	日志级别（排查问题可调 `DEBUG`）
`heg.app-log.retain-days`	`HEG_LOG_RETAIN_DAYS`	`30`	日志保留天数
`heg.log-persistence.enabled`	`HEG_LOG_PERSISTENCE_ENABLED`	`false`	业务操作日志（SQL / 转发）是否落盘
`heg.log-persistence.sql-log-path`	`HEG_SQL_LOG_PATH`	`/app/logs/sql/`	SQL 明细日志目录
`heg.log-persistence.proxy-log-path`	`HEG_PROXY_LOG_PATH`	`/app/logs/proxy/`	转发明细日志目录
`heg.log-persistence.max-file-size-mb`	`HEG_LOG_MAX_FILE_SIZE_MB`	`100`	单个日志文件大小上限（MB）
`heg.log-persistence.retain-days`	`HEG_LOG_RETAIN_DAYS`	`30`	保留天数（应用日志与业务日志共用）

# 二、运行时配置持久化

运行时配置指通过 HEG 控制台在线修改的云端连接、数据源、请求头等。其存储方式由 heg.config-persistence.type 决定：

memory（内存型）：修改即时生效，但容器重启后丢失，恢复为配置文件中的值。
file（文件型，默认）：修改会写回 file-path 指定的 YAML 文件，重启后自动恢复。

heg:
  config-persistence:
    type: file
    file-path: /app/data/heg-runtime-config.yml

重要：使用 file 模式时，持久化文件中已保存的值会覆盖环境变量提供的值。也就是说，一旦在控制台改过某项配置并保存，之后仅修改 .env 或启动参数中的同名项将不再生效，需同步清理/修改该持久化文件（或在控制台再次修改）。

因此务必挂载 /app/data，否则容器重建后运行时配置无法保留。

# 三、应用运行日志

应用运行日志由 logback 输出，控制台 + 按天滚动（主日志与 error 日志分别滚动），配置项：

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

提示：修改 HEG_LOG_PATH 时，需同步修改容器挂载的容器内路径，否则日志不会落到宿主机。日志级别可通过 HEG_LOG_LEVEL 调整，排查问题时建议临时改为 DEBUG。

# 四、业务操作日志持久化

业务操作日志记录 MySQL 执行的 SQL、转发的请求等明细，默认关闭，需要显式开启：

heg:
  log-persistence:
    enabled: true
    sql-log-path: /app/logs/sql/
    proxy-log-path: /app/logs/proxy/
    max-file-size-mb: 100
    retain-days: 30

目录	内容
`sql-log-path`	MySQL 执行的 SQL 明细日志
`proxy-log-path`	HTTP 转发请求明细日志

每个文件大小超过 max-file-size-mb 后滚动新文件；
超过 retain-days 的日志自动清理；
开启后可在 HEG 控制台的运行概览中查看，并支持在线清空。

注意：开启日志持久化会持续写入磁盘，请按需开启并规划好磁盘空间与保留天数。

# 五、数据卷挂载

容器内需要持久化的目录有两个：

容器内路径	内容
`/app/data`	运行时配置持久化文件（`heg-runtime-config.yml`）
`/app/logs`	应用运行日志、SQL / 转发明细日志

docker run 方式：

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

docker compose 方式已内置命名卷（heg-config:/app/data、heg-logs:/app/logs）。如需改用宿主机目录，替换为：

volumes:
  - ./data:/app/data
  - ./logs:/app/logs

← 快速启动信息动态配置 →