开发者交付指南

本文面向需要在私有化或离线环境中部署、集成、运维 hcip 客户端的开发者用户。HCIP 客户端是一个单二进制离线查询服务，启动后会校验产品授权、在内存中加载 DBX 数据库，并通过 HTTP 或 HTTPS 提供 IP 归属地和手机号归属地查询接口。

1. 程序能力概览

HCIP 客户端提供以下能力：

离线 IPv4/IPv6 归属地查询：通过 products.hcip 配置加载 license.lic 和 ip.dbx。
离线手机号归属地查询：通过 products.mobile 配置加载 mobile.lic 和 mobile.dbx。
HTTP/HTTPS API 服务：提供 /ip、/mobile 查询接口，/health、/version、/license 状态检查接口。
独立产品授权：hcip 与 mobile 使用独立 license 和 DBX，可分别启用、失效、续期。
DBX 内存查询：服务启动或热加载时自动加载到内存并构建查询索引。
热加载：license 授权文件与 DBX 数据库文件发生变化时自动热加载, 无需重启服务。
自动更新：可选从更新服务自动下载并替换 DBX 文件实现数据库自动更新。
运维命令：支持 license 校验、日志查看、手动更新、安装为系统服务等管理。

2. 交付文件

建议将以下文件放在同一个部署目录中，例如 /opt/hcip/：

/opt/hcip/
  hcip            # 可执行二进制文件
  config.yaml     # 配置文件
  license.lic     # IP 查询授权证书（订阅后交付）
  ip.dbx          # IP 归属地离线数据库文件
  mobile.lic      # 手机号查询授权证书（订阅后交付）
  mobile.dbx      # 手机号归属地离线数据库文件

3. 启动流程

以 hcip 二进制可执行文件为入口，默认执行方式如下：

sudo ./hcip --config config.yaml

服务启动流程：

读取 config.yaml，加载默认配置并解析相对路径。
应用命令行覆盖参数，例如 --listen、--license、--db。
校验配置字段，包括监听地址、超时时间、TLS、响应格式、更新配置和日志配置等。
分别检查 hcip 与 mobile 产品文件是否存在。
对存在的产品加载 license，校验签名、有效期和产品权限。
检查 DBX 完整性，将 DBX 加载到内存并构建 HCDB 查询索引。
创建 HTTP server，根据 tls.enabled 决定监听 HTTP 或 HTTPS。
启动后台任务：license 状态监控、license 热加载、DBX 热加载、可选自动更新。

4. 部署方式

4.1 直接运行

适用于开发、测试或临时部署。

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

验证服务：

curl 'http://127.0.0.1:8080/health'
curl 'http://127.0.0.1:8080/ip?ip=113.116.36.105'
curl 'http://127.0.0.1:8080/mobile?mobile=18138434699'

4.2 系统服务模式

适用于生产部署。系统服务模式由平台服务管理器托管：Linux 通常使用 systemd/init，macOS 使用 launchd，Windows 使用 Windows Service。

sudo /opt/hcip/hcip service install --config /opt/hcip/config.yaml # 将程序安装为系统服务
sudo /opt/hcip/hcip service start   # 以服务方式启动
sudo /opt/hcip/hcip service status  # 查看服务运行状态

停止和卸载：

sudo /opt/hcip/hcip service stop       # 停止服务
sudo /opt/hcip/hcip service uninstall  # 卸载服务

Linux/macOS 通常需要 sudo。Windows 需要在管理员终端中执行。

4.3 Daemon 模式

适用于 Linux/macOS 下的简单后台运行。

cd /opt/hcip
sudo ./hcip --config config.yaml --daemon        # 启动程序并后台运行

常用管理命令：

sudo ./hcip daemon status --config config.yaml   # 查询 daemon 模式程序运行状态
sudo ./hcip daemon restart --config config.yaml  # 重新启动程序
sudo ./hcip daemon stop --config config.yaml     # 停止程序运行
sudo ./hcip logs --config config.yaml -f         # 查询并跟踪运行日志（需开启日志配置）

注意：daemon 模式只负责后台运行和 PID 文件管理，不提供开机自启或崩溃自动拉起。生产环境优先使用系统服务模式。

5. 配置文件要点

最小示例：

server:                       # HTTP 服务配置
  listen: "0.0.0.0:8080"      # 监听地址及端口号
  read_timeout: "5s"
  write_timeout: "10s"

tls:                          # HTTPS 证书配置
  enabled: false              # 是否启用 HTTPS
  cert_file: ""               # 证书文件（公钥）
  key_file: ""                # 私钥文件

products:                     # 产品能力配置
  hcip:                       # IP 离线查询产品
    license: "license.lic"    # 交付的授权文件
    database: "ip.dbx"        # IP 离线数据库
  mobile:                     # 手机号归属地产品
    license: "mobile.lic"     # 交付的授权文件
    database: "mobile.dbx"    # 手机号离线数据库

response:                     # HTTP API 响应配置
  format: "json"              # 响应格式 JSON
  style: "snake"              # 响应字段命名风格，支持 snake 蛇形命名（小写带下划线）、camel 小驼峰命名

log:                          # 日志配置
  enabled: true               # 是否启用文件日志
  file: "hcip.log"            # 日志文件保存路径

update:                       # 自动更新配置
  enabled: true               # 是否开启自动更新
  base_url: ""                # 更新服务器地址(不可修改)
  check_interval: "6h"        # 自动更新检查间隔(小时)
  startup_delay: "30s"        # 启动后首次检查更新延迟(秒)
  timeout: "10m"              # 更新检查超时配置
  channel: "stable"           # 忽略 仅支持 stable

重要规则：

config.yaml 内的相对路径按配置文件所在目录解析，不按进程当前工作目录解析。
server.listen 必须是 host:port 格式，例如 127.0.0.1:8080、0.0.0.0:8080 或 :8080。
tls.enabled=true 时必须配置 tls.cert_file 和 tls.key_file。
response.format=json 是默认响应格式，暂不支持修改为其他响应类型。
response.style=snake 仅响应响应字段命名风格，snake 返回 request_id、long_ip 等蛇形命名；camel 返回 requestId、longIp 等小驼峰字段。
license 与 DBX 文件自动加载约有 30-60 秒延迟, 如需立即生效请重启程序。
修改配置文件、替换 https 证书、更新 hcip 可执行程序等场景仍需手动重启程序。

完整字段说明见配置文件参考。

6. API 集成方式

默认监听地址由 server.listen 决定，以下以 http://127.0.0.1:8080 为例：

curl 'http://127.0.0.1:8080/ip?ip=113.116.36.105'      # IP 归属地查询
curl 'http://127.0.0.1:8080/mobile?mobile=18138434699' # 手机号归属地查询
curl 'http://127.0.0.1:8080/health'    # 接口健康检查
curl 'http://127.0.0.1:8080/version'   # 检查离线数据库、主程序版本
curl 'http://127.0.0.1:8080/license'   # 授权证书状态检查

HTTP API 本身不包含 API Key 或 Token 鉴权。私有化部署时建议通过内网访问控制、反向代理、TLS/mTLS、网关鉴权或防火墙限制访问来源。

完整接口契约见 HTTP API 指南。

7. License 与产品权限

HCIP 客户端使用 license 控制产品能力：

products.hcip.license 控制 /ip 接口。
products.mobile.license 控制 /mobile 接口。
license 过期后服务不会立即退出，但对应产品会变为不可用，相关查询接口返回 HTTP 403。

产品续期时可直接替换 license 文件，等待约 30-60 秒后可通过 /license 接口确认状态。

cp license.lic /opt/hcip/license.lic
curl 'http://127.0.0.1:8080/license'

8. DBX 数据库与热加载

DBX 文件是加密数据库格式，服务会自动检查本地 DBX 文件变化，检测到变化约 60 秒后程序会自动加载新的 DBX 文件到内存并构建查询索引。

如需手动替换 DBX 文件建议使用临时文件加原子 rename：

cp ip.dbx /opt/hcip/ip.dbx.tmp
mv /opt/hcip/ip.dbx.tmp /opt/hcip/ip.dbx

如果新 DBX 解密失败、checksum 不匹配、权限不匹配、时间校验失败或 searcher 构建失败，服务会继续使用内存中的旧数据库。

9. 自动更新

自动更新只负责更新 DBX 文件，不更新 hcip 程序、配置文件或 https 证书。

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

行为说明：

update.enabled=true 时，服务启动后等待 startup_delay 再进行首次检查。
后台周期检查最小间隔为 1 小时，配置小于 1 小时会被提升到 1 小时。
手动命令 hcip update --config config.yaml 不要求 update.enabled=true，但要求 update.base_url 可用。
更新失败只记录日志，不会停止服务。
下载的新 DBX 通过完整校验后才会替换本地文件。
文件替换后由 DBX 热加载机制切换内存 searcher。

离线环境如果无法访问更新服务，应关闭自动更新并预置 DBX：

update:
  enabled: false

10. 常用验收清单

部署完成后建议按以下顺序验收：

确认文件存在：hcip、config.yaml、产品 license、产品 DBX。
校验配置路径是否按 config.yaml 所在目录组织。
运行 ./hcip check --license license.lic 检查 hcip license。
启动服务并查看日志，确认 license 和 DBX 加载成功。
请求 /health，确认至少一个产品可用。
请求 /version，确认 DBX source 信息符合预期。
请求 /license，确认 license 状态、有效期和剩余天数。
请求 /ip 和 /mobile，验证业务查询结果。
如果使用系统服务，重启机器或服务后再次验证。

11. 关键限制

HTTP API 无内置访问鉴权，需要部署侧控制访问边界。
自动更新不会升级程序本身，只会在服务端返回新程序版本时记录提示。
系统时间明显不准可能导致 license 或 DBX 校验失败。
daemon 模式不适合承担生产级进程守护。