客户端配置文件参考

本文说明 HCIP 客户端 config.yaml 的字段、默认值、路径解析规则和部署注意事项。

1. 配置文件位置

默认配置文件名为：

config.yaml

如果运行命令未显式指定 --config，程序会从当前工作目录读取 config.yaml：

sudo ./hcip

推荐生产环境始终使用绝对路径：

sudo ./hcip --config /opt/hcip/config.yaml

系统服务安装时也建议使用绝对路径：

sudo /opt/hcip/hcip service install --config /opt/hcip/config.yaml

2. 路径解析规则

config.yaml 中的相对路径会按配置文件所在目录解析，而不是按进程当前工作目录解析。

示例：

/opt/hcip/
  config.yaml
  license.lic
  ip.dbx

配置：

products:
  hcip:
    license: "license.lic"
    database: "ip.dbx"

无论进程从哪个目录启动，最终都会解析为：

/opt/hcip/license.lic
/opt/hcip/ip.dbx

以下字段支持相对路径解析：

products.hcip.license
products.hcip.database
products.mobile.license
products.mobile.database
tls.cert_file
tls.key_file
log.file

3. 推荐配置模板

server:
  listen: "0.0.0.0:8080"
  read_timeout: "5s"
  write_timeout: "10s"

tls:
  enabled: false
  cert_file: ""
  key_file: ""

products:
  hcip:
    license: "license.lic"
    database: "ip.dbx"
  mobile:
    license: "mobile.lic"
    database: "mobile.dbx"

response:
  format: "json"
  style: "snake"

log:
  enabled: true
  file: "hcip.log"
  level: "info"

update:
  enabled: true
  base_url: "https://ip.apimind.com"
  check_interval: "12h"
  startup_delay: "30s"
  timeout: "10m"
  channel: "stable"

4. server

服务监听与 HTTP server 超时配置。

字段	类型	代码默认值	示例值	说明
`server.listen`	string	`127.0.0.1:8080`	`0.0.0.0:8080`	HTTP/HTTPS 监听地址，必须是 `host:port` 格式
`server.read_timeout`	duration	`5s`	`5s`	读取请求超时
`server.write_timeout`	duration	`10s`	`10s`	写响应超时

监听地址示例：

server:
  listen: "127.0.0.1:8080"  # 只允许本机访问

server:
  listen: "0.0.0.0:8080"    # 允许外部访问

server:
  listen: ":8080"            # 监听所有网卡的 8080 端口

注意事项：

端口必须在 1-65535 范围内。
字段前后不能包含空格。

5. tls

HTTPS 配置。

字段	类型	默认值	说明
`tls.enabled`	bool	`false`	是否启用 HTTPS
`tls.cert_file`	string	`""`	证书文件路径
`tls.key_file`	string	`""`	私钥文件路径

启用 HTTPS 示例：

tls:
  enabled: true
  cert_file: "certs/server.crt"
  key_file: "certs/server.key"

如果 tls.enabled=true，则 cert_file 和 key_file 必须同时配置。

6. products

产品授权与数据库配置。HCIP 客户端当前支持两个产品：

hcip：IP 归属地查询。
mobile：手机号归属地查询。

字段	类型	代码默认值	说明
`products.hcip.license`	string	`license.lic`	hcip 产品 license
`products.hcip.database`	string	`ip.dbx`	hcip 产品 DBX
`products.mobile.license`	string	`mobile.lic`	mobile 产品 license
`products.mobile.database`	string	`mobile.dbx`	mobile 产品 DBX

示例：

products:
  hcip:
    license: "license.lic"
    database: "ip.dbx"
  mobile:
    license: "mobile.lic"
    database: "mobile.dbx"

产品启用规则：

文件状态	行为
license 和 DBX 都存在	加载并启用该产品
license 和 DBX 都不存在	跳过该产品
license 不存在、DBX 存在	启动失败
license 存在、DBX 不存在、`update.enabled=false`	启动失败
license 存在、DBX 不存在、`update.enabled=true`	启动阶段尝试下载 DBX
license 过期、DBX 存在	服务可启动，但该产品不可用

7. response

控制查询接口响应格式。

字段	类型	默认值	可选值	说明
`response.format`	string	`json`	`json`	响应格式
`response.style`	string	`snake`	`snake`、`camel`	JSON 字段命名风格

默认配置：

response:
  format: "json"
  style: "snake"

response.style: snake 示例字段：

{
  "request_id": "...",
  "data": {
    "long_ip": "...",
    "region_id": "...",
    "city_id": "..."
  }
}

response.style: camel 示例字段：

{
  "requestId": "...",
  "data": {
    "longIp": "...",
    "regionId": "...",
    "cityId": "..."
  }
}

请求头 X-HCIP-Response-Version: v1|v2 优先级高于配置文件，会覆盖 response.format 和 response.style，除必要兼容场景外应始终接入新版响应配置。

8. log

日志配置。

字段	类型	默认值	可选值	说明
`log.enabled`	bool	`true`	`true`、`false`	是否写入日志文件
`log.file`	string	`hcip.log`	任意路径	日志文件路径
`log.level`	string	`info`	`debug`、`info`、`warn`、`error`	日志级别

示例：

log:
  enabled: true
  file: "hcip.log"
  level: "info"

说明：

log.file 相对路径按 config.yaml 所在目录解析。
hcip logs --config config.yaml -f 默认读取该文件。
如果 log.enabled=false，hcip logs 命令需要通过 --log-file 指定文件。
log.enabled=false 时服务运行时仍会向 stderr 输出关键日志。

9. update

DBX 自动更新配置。

字段	类型	代码默认值	说明
`update.enabled`	bool	`true`	是否启动后台自动更新
`update.base_url`	string	`"https://ip.apimind.com"`	更新服务地址
`update.check_interval`	duration	`2h`	周期检查间隔，最小 1 小时
`update.startup_delay`	duration	`30s`	启动后首次检查延迟
`update.timeout`	duration	`30m`	更新检查和下载超时
`update.channel`	string	`stable`	忽略，仅支持 stable

示例：

update:
  enabled: true
  base_url: "https://ip.apimind.com"
  check_interval: "2h"
  startup_delay: "30s"
  timeout: "30m"
  channel: "stable"

行为说明：

自动更新只更新 DBX，不更新 hcip 程序、配置文件或 https 证书。
update.enabled=true 时，update.base_url 必填。
后台周期检查间隔小于 1 小时时，会按 1 小时执行。
每次检查或下载最多尝试 3 次，3 次均失败后需等待下一次检查更新时继续重试。
更新失败不会停止服务。
新 DBX 校验通过后才会原子替换本地文件。

离线环境推荐：

update:
  enabled: false

10. 命令行覆盖

启动服务时可使用命令行覆盖部分配置：

./hcip --config config.yaml --listen :8080 --license license.lic --db ip.dbx

参数	覆盖字段	说明
`--listen`	`server.listen`	覆盖监听地址
`--license`	`products.hcip.license`	只覆盖 hcip 产品 license
`--db`	`products.hcip.database`	只覆盖 hcip 产品 DBX

注意：mobile 产品没有对应的 --mobile-license 或 --mobile-db 覆盖参数，需要修改配置文件。

11. 配置校验错误示例

常见配置错误：

server.listen 缺失或不是 host:port 格式。
端口不是数字或超出 1-65535。
tls.enabled=true 但证书或私钥路径为空。
response.format 不是 json。
response.style 不是 snake 或 camel。
update.enabled=true 但 update.base_url 为空。
log.enabled=true 但 log.file 为空。
log.level 不是 debug、info、warn、error。

建议在交付部署前先执行一次启动验证，并查看启动日志。