SkeyeVSS开发日志：环境变量 .env 配置项详解

试用安装包下载 | SMS | 试用安装包下载 | 在线演示

项目源码地址https://github.com/openskeye/go-vss

1. 关于.env.prod

在 Skeyevss 中，.env.prod（或.env.prod.d）是生产环境的总开关：

• 服务端口、IP、日志路径都来自它
• SIP/媒体联动参数来自它
• 数据库、Redis、etcd 连接来自它
• 各服务配置文件（etc/.xxx.yaml）通过${SKEYEVSS_*}占位符引用它

配错 env，服务可能“能启动但不可用”

2. 配置加载机制

2.1 配置链路

1. 启动命令读取-env参数（如.env.prod）
2. 变量注入进进程环境
3. etc/.vss.yaml、etc/.backend-api.yaml等读取${SKEYEVSS_*}
4. 服务按替换后的最终值运行

2.2 常见文件角色

• .env.prod：本地/单机/非容器生产配置示例
• .env.prod.d：容器部署场景示例（含___INTERNAL_IP___占位符）

建议：上线前保留一份最终生效的 env 备份，便于回滚和审计。

3. 配置项分组详解

以下按“最常改、最容易出问题”的顺序说明。

3.1 基础运行与环境标识

注意：

• 同局域网部署可将EXTERNAL_IP与INTERNAL_IP设为同值
• 跨网/公网接入时必须准确区分内外网 IP

3.2 服务启用与数据存储

注意：

• 生产优先mysql
• 视频/日志目录建议挂载到独立数据盘

3.3 日志与排障开关

SIP 日志路径：
$SKEYEVSS_SERVER_LOG_PATH/$SKEYEVSS_VSS_NAME/sip/

3.4 鉴权与密钥

注意：

• 如果需要针对访问DB做鉴权可根据SKEYEVSS_U_KEY_*做详细配置，示例代码中目前未使用

3.5 MySQL / Redis / etcd

MySQL

• SKEYEVSS_MYSQL_HOST
• SKEYEVSS_MYSQL_PORT
• SKEYEVSS_MYSQL_USERNAME
• SKEYEVSS_MYSQL_PASSWORD
• SKEYEVSS_MYSQL_DB_NAME_BASE

Redis

• SKEYEVSS_REDIS_HOST
• SKEYEVSS_REDIS_PORT
• SKEYEVSS_REDIS_PASSWORD

etcd

• SKEYEVSS_ETCD_HOST
• SKEYEVSS_ETCD_CLIENT_PORT
• SKEYEVSS_ETCD_PEER_PORT

注意：

• DB RPC 连不上时，80% 先查 etcd 地址和端口

3.6 Web 代理（前端入口）

3.7 媒体服务SMS联动（播放链路核心）

关键项：

• SKEYEVSS_MEDIA_SERVER_PORT
• SKEYEVSS_MEDIA_SERVER_CONF_DEF
• SKEYEVSS_MEDIA_SERVER_NOTIFY_ON_PUB_START
• SKEYEVSS_MEDIA_SERVER_NOTIFY_ON_PUB_STOP
• SKEYEVSS_MEDIA_SERVER_NOTIFY_ON_SUB_START
• SKEYEVSS_MEDIA_SERVER_NOTIFY_ON_RTMP_CONNECT

这些回调 URL 若不可达，会导致“设备在线但播放异常”。

3.8 VSS（GB28181 核心）

最关键参数：

• SKEYEVSS_VSS_PORT（SIP）
• SKEYEVSS_VSS_HTTP_PORT（HTTP 回调）
• SKEYEVSS_VSS_SSE_PORT（SSE）
• SKEYEVSS_VSS_SIP_ID
• SKEYEVSS_VSS_SIP_DOMAIN
• SKEYEVSS_VSS_SIP_PASSWORD
• SKEYEVSS_VSS_SIP_USE_EXTERNAL_WAN
• SKEYEVSS_VSS_USE_EXTERNAL_IP

公网接入建议：

• 设备跨公网时，确认EXTERNAL_IP、USE_EXTERNAL_WAN和防火墙端口策略一致

3.9 各微服务端口与配置文件绑定

4. 上线前必查清单

1. SKEYEVSS_INTERNAL_IP/EXTERNAL_IP与实际网络一致
2. SKEYEVSS_DATABASE_TYPE与实际依赖一致
3. SKEYEVSS_VSS_SIP_*与设备侧平台参数一致
4. 媒体回调SKEYEVSS_MEDIA_SERVER_NOTIFY_*可达
5. SKEYEVSS_SERVER_LOG_PATH、录像目录有写权限
6. 所有服务端口无冲突，防火墙已放行

5. 三个最常见误配案例

案例 1：后台正常，视频黑屏

原因：媒体回调地址错误或 VSS SIP 参数不一致
排查：检查SKEYEVSS_MEDIA_SERVER_NOTIFY_*、SKEYEVSS_VSS_SIP_*

案例 2：DB RPC 启动成功但业务报错

原因：etcd 配置错误，服务发现失败
排查：检查SKEYEVSS_ETCD_HOST、SKEYEVSS_ETCD_CLIENT_PORT

案例 3：公网设备注册不上

原因：SKEYEVSS_VSS_SIP_USE_EXTERNAL_WAN=false或外网地址错误
排查：检查SKEYEVSS_EXTERNAL_IP、公网端口放行策略

6. 推荐配置策略

6.1 开发环境

• 日志可用plain + info
• 可启用sqlite
• 内外网 IP 可先同值（纯内网）

6.2 生产环境

• 日志建议file + json + error/info
• 使用mysql
• 开启 SIP 文件日志，做日志轮转与归档
• 禁止默认密码与空密钥

7. 变更流程建议

.env.prod变更建议按以下流程执行：

1. 变更前备份旧文件
2. 按模块修改并复核
3. 灰度环境验证
4. 低峰时段发布
5. 发布后做播放链路与设备注册回归测试