客户端运维与排障手册

本文面向 HCIP 客户端私有化部署后的运维、开发联调和现场排障。

1. 常用命令总览

./hcip --help
./hcip version
./hcip --config config.yaml
./hcip serve --config config.yaml
./hcip check --license license.lic
./hcip update --config config.yaml
./hcip logs --config config.yaml -f
./hcip service status
./hcip daemon status --config config.yaml

2. 启动与停止

2.1 前台启动

适合开发、测试和临时排障。

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

或：

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

前台启动后按 Ctrl+C 停止服务。

2.2 系统服务

安装：

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 restart

停止：

sudo /opt/hcip/hcip service stop

卸载：

sudo /opt/hcip/hcip service uninstall

说明：

Linux/macOS 通常需要 sudo。
Windows 需要管理员终端。
service install 会保存配置文件的绝对路径。
修改配置后通常需要重启服务；替换 license 或 DBX 不一定需要重启，等待热加载即可。

2.3 Daemon 模式

启动：

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

查看状态：

sudo ./hcip daemon status

重启：

sudo ./hcip daemon restart

停止：

sudo ./hcip daemon stop

自定义 PID 和日志捕获路径：

./hcip --config config.yaml --daemon \
  --pid-file /var/run/hcip.pid \
  --log-file /var/log/hcip.log

daemon 模式不提供开机自启或崩溃自动拉起。生产环境建议使用系统服务模式。

3. 日志查看

默认日志文件由 config.yaml 中的 log.file 决定：

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

查看运行日志：

./hcip logs --config /opt/hcip/config.yaml

查看最近 100 行：

./hcip logs --config /opt/hcip/config.yaml -n 100

持续跟随：

./hcip logs --config /opt/hcip/config.yaml -f

显式指定日志文件：

./hcip logs --log-file /var/log/hcip.log -f

如果 log.enabled=false，hcip logs --config 无法从配置中读取日志文件，需要使用 --log-file。

4. 健康检查

基础检查：

curl 'http://127.0.0.1:8080/health'

预期成功：

{
  "ok": true,
  "status": "running",
  "products": {
    "hcip": {
      "status": "valid",
      "valid": true,
      "message": "license valid"
    }
  }
}

如果返回 HTTP 403，表示当前没有任何已启用且 license 有效的产品。继续检查：

curl 'http://127.0.0.1:8080/license'
curl 'http://127.0.0.1:8080/version'

5. License 校验与续期

部署前校验 license：

./hcip check --license /opt/hcip/license.lic

输出示例：

{
  "valid": true,
  "subject": "customer-a",
  "not_before": "2026-01-01T00:00:00Z",
  "not_after": "2027-01-01T00:00:00Z",
  "days_left": 205
}

查看运行时 license 状态：

curl 'http://127.0.0.1:8080/license'

续期步骤：

将新的 license 文件复制到部署目录。
覆盖旧 license 文件。
等待约 30-60 秒热加载。
调用 /license 验证状态。

示例：

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

说明：

license.lic 对应 /ip。
mobile.lic 对应 /mobile。
某个产品 license 失效只影响该产品接口。

6. 数据库替换

6.1 热替换 DBX

推荐使用临时文件加原子 rename：

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

然后等待约 60 秒，验证：

curl 'http://127.0.0.1:8080/version'
curl 'http://127.0.0.1:8080/ip?ip=113.116.36.105'

如果新 DBX 加载失败，服务会继续使用内存中旧 searcher，并在日志中记录失败原因。

7. 手动更新 DBX

执行一次更新检查和应用：

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

说明：

手动更新不要求 update.enabled=true。
必须配置有效的 update.base_url。
每次检查或下载最多重试 3 次。
只更新 DBX，不更新程序、license、配置或证书。
成功替换 DBX 后，运行中服务仍依赖 DBX 热加载切换内存 searcher。

8. 自动更新排查

确认配置：

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

排查顺序：

确认服务能访问更新服务地址。
确认 license 有效且产品已启用。
确认当前 DBX 文件存在且完整。
查看日志中 update 前缀的记录。
使用 ./hcip update --config config.yaml 手动触发一次，观察错误输出。

常见失败原因：

更新服务不可达。
update.base_url 为空或被正式构建内置地址覆盖。
license 已过期。
服务端没有可用更新。
下载 URL 过期。
文件大小或 SHA-256 校验失败。
DBX 数据库与 license 不匹配。
本地系统时间异常导致 DBX 校验失败。
目标目录无写权限，无法替换 DBX。

9. HTTPS 排查

启用 HTTPS 配置：

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

检查项：

证书文件和私钥文件是否存在。
路径是否相对于 config.yaml 所在目录。
进程用户是否有读取权限。
客户端请求是否使用 https://。
证书域名或 IP 是否与访问地址匹配。

验证：

curl -k 'https://127.0.0.1:8080/health'

-k 只建议用于测试自签名证书，不建议生产调用方长期使用。

10. 配置变更生效规则

变更类型	是否自动生效	推荐操作
替换 `license.lic`	是，约 30-60 秒	调用 `/license` 验证
替换 `mobile.lic`	是，约 30-60 秒	调用 `/license` 验证
替换 `ip.dbx`	是，约 60 秒	调用 `/version` 和 `/ip` 验证
替换 `mobile.dbx`	是，约 60 秒	调用 `/version` 和 `/mobile` 验证
修改 `server.listen`	否	重启服务
修改 `tls.*`	否	重启服务
修改 `response.*`	否	重启服务
修改 `update.*`	否	重启服务
修改 `log.*`	否	重启服务

11. 常见故障

11.1 启动报 `server.listen must be in host:port form`

原因：server.listen 格式错误。

修复：

server:
  listen: "0.0.0.0:8080"

11.2 启动报 license file not found

原因：配置中的 license 路径不存在，或相对路径理解错误。

排查：

ls -l /opt/hcip/license.lic

确认路径相对于 config.yaml 所在目录，而不是命令执行目录。

11.3 启动报 database file not found

原因：license 存在，但 DBX 不存在且未开启自动更新。

处理方式：

放置正确 DBX 文件。
或配置 update.enabled=true 并确保更新服务可用，让启动阶段 bootstrap 下载。

11.4 `/health` 返回 403

原因：没有任何产品处于可用状态。

排查：

curl 'http://127.0.0.1:8080/license'
curl 'http://127.0.0.1:8080/version'
sudo ./hcip logs --config /opt/hcip/config.yaml -n 200

重点检查 license 是否过期、产品是否被跳过、DBX 是否加载失败。

11.5 `/ip` 返回 403，但 `/mobile` 正常

原因：hcip 产品 license 不可用，不影响 mobile 产品。

排查：

curl 'http://127.0.0.1:8080/license'
sudo ./hcip check --license /opt/hcip/license.lic

11.6 `/mobile` 返回 403，但 `/ip` 正常

原因：mobile 产品 license 不可用，不影响 hcip 产品。

排查：

curl 'http://127.0.0.1:8080/license'
sudo ./hcip check --license /opt/hcip/mobile.lic

11.7 DBX 热加载后版本没有变化

可能原因：

文件未真正替换。
替换后还未经过下一轮 60 秒轮询。
新 DBX 校验失败，服务继续使用旧 searcher。
license 当前不可用，DBX reload 被跳过。

排查：

sudo ./hcip logs --config /opt/hcip/config.yaml -n 200
curl 'http://127.0.0.1:8080/version'

11.8 提示 system time sanity check failed

原因：本地系统时间明显早于 DBX 构建时间，超过最大时差容忍范围。

处理：

date

修正系统时间或 NTP 同步后重启服务。

11.9 端口被占用

表现：启动监听失败。

处理：

修改 server.listen 使用其他端口。
或停止占用端口的进程。

示例：

server:
  listen: "0.0.0.0:18080"

修改后重启服务。

11.10 `hcip logs` 提示 log is disabled

原因：log.enabled=false，命令无法从配置读取日志文件。

处理：

./hcip logs --log-file /path/to/hcip.log -f

或启用日志：

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

然后重启服务。

12. 升级程序版本

程序本身不会被自动更新。升级 hcip 二进制建议按以下流程：

备份当前部署目录。
停止服务。
替换 hcip 二进制。
保留原 config.yaml、license 和 DBX。
启动服务。
验证 /version、/health、业务查询接口。

示例：

sudo /opt/hcip/hcip service stop
cp hcip /opt/hcip/hcip
sudo /opt/hcip/hcip service start
/opt/hcip/hcip service status
curl 'http://127.0.0.1:8080/version'

13. 交付验收

建议交付时保留以下信息：

hcip 程序版本：./hcip version
配置文件路径：例如 /opt/hcip/config.yaml
服务运行方式：前台、系统服务或 daemon
监听地址：server.listen
是否启用 HTTPS
hcip DBX source name：来自 /version
mobile DBX source name：来自 /version
license subject 和过期时间：来自 /license
一组 IP 查询样例及返回结果
一组手机号查询样例及返回结果
日志文件路径

验收命令：

sudo ./hcip version
curl 'http://127.0.0.1:8080/health'
curl 'http://127.0.0.1:8080/version'
curl 'http://127.0.0.1:8080/license'
curl 'http://127.0.0.1:8080/ip?ip=113.116.36.105'
curl 'http://127.0.0.1:8080/mobile?mobile=18138434699'

运维与排障手册