前置条件
为了保证 multishot accept 和 SQPOLL 稳定性，建议使用 6.1+ 内核。先确认你的内核版本：
安装二进制
方式 A（推荐）：用 install.sh 安装最新 Release
/usr/local/bin/arc-gateway。
当前发布资产是 arc-gateway-linux-x86_64 和 arc-gateway-linux-arm64。
Systemd（裸机或虚机）
安装
先安装 systemd 服务单元和默认配置文件：- 二进制：
/usr/local/bin/arc-gateway - 配置文件：
/etc/arc/arc.json
服务单元参数
服务单元路径：/etc/systemd/system/arc-gateway.service。
默认开启的安全加固项：
NoNewPrivileges=yesPrivateTmp=yesProtectSystem=strictProtectHome=yesProtectKernelTunables=yesProtectControlGroups=yesRestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
热更新
修改/etc/arc/arc.json 后执行：
常用命令
Kubernetes
Kubernetes 清单都在deploy/kubernetes/ 下，按顺序应用：
创建的资源
应用前：先设置认证 token
在部署前，Secret 必须写入真实 token：control_plane.auth_token 与该值一致。
建议覆盖的 ConfigMap 关键字段
Deployment 规格
存活探针：
GET /healthz（9090 端口），initialDelaySeconds=5，periodSeconds=10
就绪探针： GET /healthz（9090 端口），initialDelaySeconds=3，periodSeconds=5
优雅下线
preStop hook 会先执行 sleep 5，给负载均衡器留出摘流时间，再由容器接收 SIGTERM。terminationGracePeriodSeconds=35 与该下线窗口对齐。
Kubernetes 中的 XDP/eBPF
XDP 需要NET_ADMIN 和 SYS_ADMIN capability，并要求 privileged: true。默认清单里是关闭状态（注释掉的 YAML），多数托管 Kubernetes 平台也不支持这类能力。
启动流程（arc-daemon）
执行arc-gateway --config arc.yaml 后的启动序列如下：
node.workers。如果设置为 0，会使用 std::thread::available_parallelism() 自动识别。
生产上线检查清单
上线前建议逐项确认：- 将
node.workers设为0（自动）或按进程可用 CPU 核数固定 - 按预期并发连接量设置
max_connections - 在 systemd 单元里设置
LimitNOFILE（默认1048576） - 在监听器启用
SO_REUSEPORT，让 Arc 在多 worker 间无锁分摊连接 - 按峰值并发请求调整上游
pool.max_idle - 如果 control plane 对外可达，务必设置高强度随机
control_plane.auth_token - 将指标服务绑定到回环地址（
observability.metrics_bind: "127.0.0.1:9090"）或用防火墙保护 9090；该端点没有内建鉴权 - 配置日志轮转（
logging.output.rotation.max_size与max_files） - 在 Prometheus 加入
<host>:9090/metrics采集目标 - 验证热更新：
kill -HUP <pid>后确认/metrics中arc_config_reload_total递增
故障排查
systemd: Failed to start arc-gateway.service
systemd: Failed to start arc-gateway.service
先看
journalctl -xe -u arc-gateway。最常见原因是 ExecStart 指向的二进制不存在，或配置文件路径写错。可用 arc-gateway --config /etc/arc/arc.json --check（如果版本支持 --check）辅助验证，或直接检查启动日志。Arc 重启循环并提示 io_uring: Operation not supported
Arc 重启循环并提示 io_uring: Operation not supported
当前内核可能不支持请求的 io_uring 特性。可先关闭 SQPOLL（
io_uring.sqpoll: false），并适当调小 uring_entries。最低要求内核为 Linux 5.10。Kubernetes Pod 卡在 CrashLoopBackOff
Kubernetes Pod 卡在 CrashLoopBackOff
执行
kubectl logs -n arc-system <pod> 排查。常见原因包括：arc-gateway-secret 不存在或缺少 auth-token；ConfigMap 的 arc.toml 指向了启动阶段不可达的上游地址；资源上限过低，需要提高 resources.limits.memory。bind: address already in use
bind: address already in use
说明端口被其他进程占用。可用
ss -tlnp | grep 8080 检查。如果是 Pod 重启场景，可能旧 Pod 尚未完全退出，可适当增大 terminationGracePeriodSeconds。Hot reload（SIGHUP）不生效
Hot reload（SIGHUP）不生效
node.workers、监听器 bind 地址和 io_uring.uring_entries 等字段必须完整重启才能生效，其他字段才可在线生效。可检查 arc_config_reload_total 确认是否触发了热更新。