HK-2 上搭建 API 服务的要点

发布时间:2026-07-04 19:06

API 服务和网页不同的地方在于没有页面兜底，一个 500 响应对调用方就是一次故障，调用方的用户会跟着一起感知到。在顺云 HK-2 上搭建对外 API，要点集中在 HTTPS、限流、日志监控三处，按步骤逐项落实。 第一步：HTTPS 是底线 证书用 certbot 签发：apt install certbot python3-certbot-nginx && certbot --nginx -d api.example.com，签发后强制 HTTP 跳转 HTTPS。API 场景建议同时关掉 TLS 1.0 和 1.1，Nginx 里写 ssl_protocols TLSv1.2 TLSv1.3;。调用方多是程序，不存在老旧浏览器的兼容顾虑，没有理由保留弱协议；证书到期前 certbot 会自动续期，也不用惦记。证书链要配完整，漏了中间证书时程序端会报证书验证失败，浏览器却未必看得出来。 第二步：限流保护自己 公开的 API 一定会被扫描和刷量，限流不是可选项。网关层用 Nginx 的 limit_req： limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s; limit_req zone=api burst=20; 单 IP 每秒十次、突发二十次，参数按业务实际调整，移动端应用的正常请求频率要先摸清再定线。应用层再叠一层按 API Key 的配额，防止单个调用方吃光资源；配额超限时返回明确的错误码，让调用方知道该怎么处理。限流参数的变更走灰度：先对部分接口生效，观察一天再推全量。 第三步：日志与监控 访问日志记录调用方 IP、路径、状态码、耗时，前三项 Nginx 默认格式已含，耗时需在格式里加 $request_time。排障看 /var/log/nginx/access.log，用 goaccess 之类工具能快速出统计，日志记得按天切割。监控盯三件事：接口可用性（每分钟 curl -s -o /dev/null -w "%{http_code}" 探活）、5xx 比例、P95 响应时间，任一越阈值即告警。探活接口要复用真实业务路径，单独造的健康检查接口测不出依赖故障。 第四步：变更与回退 调用方不受你控制，发版要向后兼容：字段只增不删，废弃字段先标记、观察一个周期再下线；部署出错时能在一分钟内切回上一版本，回退演练和发布本身一样重要。版本号写进响应头，调用方报障时报出版本号，定位问题事半功倍。 收尾：对外 API 的口碑来自稳定性。限流和监控先于功能完善，调用方才会放心把业务挂上来。