跳转到主要内容

​
环境要求

要求最低版本推荐版本
Linux 内核5.106.1+
Rust 工具链1.75最新稳定版
Redis（可选）6.07.x，仅在集群级限流时需要
为了保证 multishot accept 和 SQPOLL 稳定性，建议使用 6.1+ 内核。先检查当前版本： 
uname -r
如果机器上还没有 Rust，请先安装： 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable

​
第 1 步：编译

git clone https://github.com/shuakami/Arc
cd arc
cargo build -p arc-gateway --release
可执行文件在 ./target/release/arc-gateway。如果你要做开发调试，可去掉 --release 生成带调试符号的版本。

​
第 2 步：写最小配置

Arc 支持 JSON、TOML、YAML 三种格式，会通过文件后缀自动识别。新建 arc.yaml： 
node:
  workers: 0          # 0 = 从 available_parallelism() 自动识别 CPU 数
  read_timeout: 30s
  write_timeout: 30s
  idle_timeout: 60s

listeners:
  - name: http
    kind: http
    bind: "0.0.0.0:8080"

observability:
  metrics_bind: "127.0.0.1:9090"

upstreams:
  - name: app
    discovery:
      type: static
      endpoints:
        - address: "127.0.0.1:3000"
    pool:
      max_idle: 128
      idle_ttl: 30s

routes:
  - name: root
    match:
      path: "/{*rest}"
    action:
      upstream: app

​
第 3 步：启动测试后端

任何监听在 3000 端口的 HTTP 服务都可以。用 Python 内置服务器即可： 
python3 -m http.server 3000 &

​
第 4 步：运行 Arc

./target/release/arc-gateway --config arc.yaml

​
第 5 步：验证

# 看代理响应
curl -i http://localhost:8080/

# 健康检查
curl http://localhost:9090/healthz
# 预期：ok

# Prometheus 指标
curl http://localhost:9090/metrics
# 可关注：arc_requests_total, arc_active_current

​
添加速率限制

Arc 使用 GCRA（Generic Cell Rate Algorithm）做限流。在任意路由上添加 rate_limit： 
routes:
  - name: api
    match:
      path: /api/{*rest}
    action:
      upstream: app
    rate_limit:
      qps: 100
      burst: 200
      key:
        by: client_ip
保存后 Arc 会监听配置变化，并在约 500ms 内应用，不会中断现有连接。

​
添加 TLS

先准备证书，再增加一个 TLS 监听器： 
listeners:
  - name: https
    kind: https
    bind: "0.0.0.0:8443"
    tls:
      certificates:
        - sni: example.com
          cert_pem: ./certs/example.com.crt
          key_pem: ./certs/example.com.key
证书文件会在启动时读取，并在热更新时重新加载。自动签发证书请看 TLS 与证书。

​
添加 ACME（Let’s Encrypt）

listeners:
  - name: https
    kind: https
    bind: "0.0.0.0:8443"
    tls:
      acme:
        email: you@example.com
        domains: [example.com]
        account_key:
          algorithm: ed25519
          encrypted_key_path: ./acme-key.enc
          passphrase:
            type: env
            name: ACME_KEY_PASSPHRASE
        challenge:
          type: tls_alpn_01
          listener: https

​
热更新

Arc 会监控配置文件修改时间。每次修改后可执行： 
# 通过 systemd
systemctl reload arc-gateway

# 或直接发信号
kill -HUP $(pidof arc-gateway)
监听地址、worker 数、io_uring ring 尺寸和 control plane 绑定地址变更都需要重启进程。其余变更（路由、上游、限流、TLS 证书、插件）可在线生效。

​
故障排查

检查监听器 bind 地址和端口是否和你访问的一致。如果你绑定的是 127.0.0.1:8080，那从其他机器访问会被拒绝。
io_uring 需要 Linux 5.10+。在 5.10 到 5.19 之间，部分 SQPOLL 操作可能需要更高权限。请设置 RLIMIT_MEMLOCK 或使用 CAP_SYS_ADMIN。在容器里还要确认 seccomp 没有拦截 io_uring 相关 syscall。
说明配置了 control plane auth_token，但请求没有带认证头。请加上：curl -H "Authorization: Bearer <token>" http://localhost:22100/healthz。
先确认文件的 mtime 是否真的变化（有些编辑器会先写临时文件再替换）。然后手动发送 SIGHUP：kill -HUP $(pidof arc-gateway)。同时检查 /metrics 里的 arc_config_reload_total 是否有增长。
确认 certificates 中的 sni 与访问主机名完全一致，或使用 *.example.com 这种通配符。数组中的第一张证书会作为兜底证书。
TLS-ALPN-01 需要 443 端口可达，HTTP-01 需要 80 端口可达。请检查防火墙和监听器 bind 是否对公网可达。ACME 报错会写入访问日志中的 kind: "system" 记录。

​
下一步

配置参考

全量配置字段说明。

安全防护

XDP、限流和 L7 防护。

部署指南

systemd 与 Kubernetes 部署。

可观测性

指标、日志与追踪。