Aegis AI Gateway 使用手册

快速信息

AI 服务与 OpenAI 兼容接口

这是 Aegis 的核心能力。Web 管理页的 AI 服务 页面用于配置客户端 API Key、虚拟模型到上游模型的路由、Provider 端点、并发上限和用量审计。业务应用使用 OpenAI 兼容接口访问，不需要直接持有上游 Provider 密钥：

curl http://192.168.8.1/v1/chat/completions \
  -H 'Authorization: Bearer <AI_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "hello"}
    ],
    "stream": false
  }'

1. 先在 Web 管理的 AI 服务页面创建客户端 API Key。
2. 配置虚拟模型名，例如 gpt-4，并映射到真实 Provider 与上游模型。
3. 填写上游 Provider API Key 和 Endpoint，密钥只保存在网关侧。
4. 设置并发上限和使用边界，避免单个应用占满 AI 服务能力。
5. 通过 AI 用量统计查看请求、缓存、拒绝、Token 估算和 Provider 调用情况。

如需流式响应，在请求体中设置 "stream": true，服务会返回 text/event-stream。

部署包清单

以下文件随产品发布包提供。AI 服务可通过 Docker、通用 Linux 或边缘硬件部署；硬件刷机包只是其中一种交付形态。

cd /path/to/aegis-release
sha256sum -c SHA256SUMS

边缘硬件镜像部署说明

SD 卡启动包

1. 确认目标设备为兼容 RK3399 边缘硬件，准备容量不小于 8GB 的 microSD 卡。
2. 使用镜像写入工具把 rk3399-sd-debian-bookworm-core-4.19-arm64-aegis-20260527-delivery.img 写入 microSD。
3. 插入设备，WAN 接上游网络，LAN 接电脑或交换机，通电启动。
4. 电脑从 LAN 获取地址后访问 http://192.168.8.1。

cd /path/to/aegis-release
sudo dd if=rk3399-sd-debian-bookworm-core-4.19-arm64-aegis-20260527-delivery.img \
  of=/dev/sdX bs=4M conv=fsync status=progress

eMMC / eFlasher 包

1. 仅用于带板载 eMMC 的兼容设备；没有板载 eMMC 的硬件只能使用 SD 启动镜像。
2. 把 rk3399-eflasher-debian-bookworm-core-4.19-arm64-aegis-20260527-delivery.img 写入 microSD。
3. 插入设备并启动，eFlasher 会按内置 eflasher.conf 自动把 Aegis 系统写入板载 eMMC。若未写入，请先确认设备从 eFlasher microSD 启动、lsblk 能看到 eMMC，并查看串口或 eFlasher 日志。
4. 刷写完成断电，取出 microSD，再从 eMMC 启动。

默认边缘硬件端口映射：eth0 为 WAN，eth1 接入 br-lan 作为 LAN。LAN 默认地址为 192.168.8.1，DHCP 地址池为 192.168.8.100-192.168.8.200。

Web 与 AI 服务入口：硬件镜像启动后，LAN 侧默认访问 http://192.168.8.1 进入控制台；AI 客户端访问同主机的 /v1/chat/completions，登录账号为 root，默认密码为 123456。

Linux 系统部署包运行说明

Linux 部署包适合直接安装到 Debian/Ubuntu 等 systemd 主机。请选择与 CPU 架构匹配的包：amd64 用 x86_64，arm64 用 aarch64。双网口完整网关使用 generic-linux，单网卡 VLAN 单臂路由使用 single-nic-vlan。

安装

cd /path/to/aegis-release

# amd64 示例；arm64 主机请换成 aarch64 包名
tar -xzf aegis-ai-gateway-0.1.0-beta.1+20260527-delivery-generic-linux-x86_64-unknown-linux-gnu.tar.gz -C /tmp/aegis-install
sudo install -d /etc/aegis /var/lib/aegis /var/log/aegis /etc/systemd/system /usr/local/bin
sudo install -m 755 /tmp/aegis-install/usr/local/bin/aegis-gateway /usr/local/bin/aegis-gateway
sudo install -m 644 /tmp/aegis-install/etc/aegis/aegis.conf /etc/aegis/aegis.conf
sudo install -m 644 /tmp/aegis-install/etc/systemd/system/aegis-gateway.service /etc/systemd/system/aegis-gateway.service
sudo install -m 644 /tmp/aegis-install/var/lib/aegis/aegis.redb /var/lib/aegis/aegis.redb

# 完整网关模式：安装 daemon/firewall/web-full 三件套
cd /tmp/aegis-install
sudo usr/local/share/aegis/install-linux-full.sh

配置和启动

启动前编辑 /etc/aegis/aegis.conf，把 wan=eth0,dhcp 和 lan=eth1,... 改成目标主机真实网卡。若作为完整网关，WAN/LAN 必须是不同物理接口或 VLAN 子接口。

sudo /usr/local/bin/aegis-gateway --config /etc/aegis/aegis.conf validate
sudo /usr/local/bin/aegis-gateway --config /etc/aegis/aegis.conf production-check
sudo systemctl daemon-reload
sudo systemctl enable --now aegis-gateway.service
sudo systemctl status aegis-gateway.service --no-pager

单独启动 Web 管理服务：

sudo /usr/local/bin/aegis-gateway --config /etc/aegis/aegis.conf \
  web-serve --bind 0.0.0.0:80 \
  --system-auth \
  --db-file /var/lib/aegis/aegis.redb \
  --traffic-db-file /var/lib/aegis/aegis-traffic.redb

Web 管理 URL：上例监听 0.0.0.0:80，浏览器访问 http://<Linux服务器IP>/；如果改成其他端口，例如 8080，则访问 http://<Linux服务器IP>:8080/。

Docker 部署包运行说明

Docker 部署包使用 deploy/aegis.docker-egress.conf 形态，默认 dhcp=disabled，适合在已有路由器继续负责 DHCP 的场景中提供 Web、DNS、AI 网关和出口策略能力。完整交付包同时提供 aegis-ai-gateway-docker-image-arm64-20260527-delivery.tar 和 aegis-ai-gateway-docker-image-amd64-20260527-delivery.tar，可用 docker load -i 导入。

准备配置和运行镜像

sudo install -d /etc/aegis /var/lib/aegis
cd /path/to/aegis-release

# amd64 示例；arm64 主机请换成 aarch64 包名
mkdir -p /tmp/aegis-docker
tar -xzf aegis-ai-gateway-0.1.0-beta.1+20260527-delivery-docker-egress-x86_64-unknown-linux-gnu.tar.gz -C /tmp/aegis-docker
sudo install -m 644 /tmp/aegis-docker/etc/aegis/aegis.conf /etc/aegis/aegis.conf
sudo install -m 644 /tmp/aegis-docker/var/lib/aegis/aegis.redb /var/lib/aegis/aegis.redb

cat >/tmp/aegis-docker/Dockerfile.runtime <<'EOF'
FROM debian:bookworm-slim
RUN apt-get update \
  && apt-get install -y --no-install-recommends ca-certificates iproute2 iputils-ping nftables traceroute \
  && rm -rf /var/lib/apt/lists/*
COPY usr/local/bin/aegis-gateway /usr/local/bin/aegis-gateway
ENTRYPOINT ["/usr/local/bin/aegis-gateway"]
EOF

docker build --platform linux/amd64 -t aegis-ai-gateway:runtime-amd64 -f /tmp/aegis-docker/Dockerfile.runtime /tmp/aegis-docker

# 或使用包内完整功能脚本
cd /tmp/aegis-docker
IMAGE=aegis-ai-gateway:runtime-amd64 PLATFORM=linux/amd64 usr/local/share/aegis/run-docker-full.sh build

编辑 /etc/aegis/aegis.conf，确认 wan、lan、DNS、代理出口节点和规则符合 Docker 主机网络。

host network 运行

# DNS/Daemon，真实 nft/TUN/路由场景需要 privileged、NET_ADMIN 和 /dev/net/tun
docker run --rm --platform linux/amd64 \
  --name aegis-egress-daemon \
  --privileged \
  --device /dev/net/tun \
  --cap-add NET_ADMIN \
  --network host \
  -v /etc/aegis/aegis.conf:/etc/aegis/aegis.conf:ro \
  -v /var/lib/aegis:/var/lib/aegis \
  aegis-ai-gateway:runtime-amd64 \
  --config /etc/aegis/aegis.conf daemon-serve --bind 0.0.0.0:53

# Web 管理
docker run --rm --platform linux/amd64 \
  --name aegis-egress-web \
  --network host \
  -v /etc/aegis/aegis.conf:/etc/aegis/aegis.conf:ro \
  -v /var/lib/aegis:/var/lib/aegis \
  aegis-ai-gateway:runtime-amd64 \
  --config /etc/aegis/aegis.conf web-serve --bind 0.0.0.0:8080

Web 管理 URL：上例使用 host network 并监听 0.0.0.0:8080，浏览器访问 http://<Docker主机IP>:8080/。如果使用包内 run-docker-full.sh web 默认监听 0.0.0.0:80，则访问 http://<Docker主机IP>/。

单网卡主机注意事项

不要把同一个未打 VLAN 的物理网卡同时配置为 WAN 和 LAN。单网卡完整网关应使用 VLAN，例如 enp1s0.10 做 WAN，enp1s0.20 做 LAN；否则只能作为旁路服务或管理服务运行。

AI 管理控制台

Web 控制台用于配置 AI 服务、Provider、模型路由、API Key、用量审计和网络出口策略。硬件镜像默认监听 0.0.0.0:80，Linux/Docker 可按部署命令指定监听地址，使用系统账号认证。默认登录信息：

常用页面

• 状态/概览：查看服务状态、AI 请求、审计日志、系统日志和生产检查。
• AI 服务：管理 AI API Key、模型路由、上游 Provider、并发上限和用量统计。
• 模型与 Provider：配置 OpenAI/OpenRouter/Anthropic/Gemini/自定义兼容端点。
• 成本与审计：查看请求记录、Token 估算、拒绝原因和关键配置变更。
• 网络出口策略：按域名、IP、国家、设备、端口设置直连、代理或拦截规则。
• 代理出口节点：按需添加 Shadowsocks、Trojan、VLESS、Hysteria2 或 Direct 出口。
• 诊断：运行接口状态、网络摘要、系统指标、服务状态、配置验证和生产检查。

服务状态命令

systemctl status aegis-gateway-web --no-pager
systemctl status aegis-gateway-daemon --no-pager
systemctl status aegis-gateway-firewall --no-pager
journalctl -u aegis-gateway-web -n 100 --no-pager

修改默认密码

passwd root

运维检查与故障排查

部署包下载

通过网盘分享的文件：aegis_ai_gateway。链接：https://pan.baidu.com/s/100rCwY4vlK6jndipz-HcDA，提取码：4avw。

基础检查

/usr/local/bin/aegis-gateway --config /etc/aegis/aegis.conf validate
/usr/local/bin/aegis-gateway --config /etc/aegis/aegis.conf production-check
/usr/local/bin/aegis-gateway --config /etc/aegis/aegis.conf nft-check
ss -lntup | grep -E ':(53|80|12345)\b'

网络不通时

• 确认 WAN 口接上游网络，LAN 客户端拿到 192.168.8.0/24 地址。
• 确认配置中的 WAN/LAN 接口名和实际设备一致。
• 先运行 Web 页面里的生产检查和防火墙应用演练，再执行真实应用。
• Docker 场景确认容器使用 host network，并具备需要的网络权限。

安全建议

• 首次登录后立即修改 root 密码。
• 不要把 Web 管理端口直接暴露到公网。
• 真实防火墙 apply/rollback 只在目标设备或受控容器内执行。
• 上线前保存当前 /etc/aegis/aegis.conf 和 /var/lib/aegis 备份。