企业官网建设流程全解析

Agent Zero VPS 部署完整指南：Docker 容器化 + Apache 反向代理 + SSL/TLS + 多实例实战

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

本文是一份面向生产环境的 Agent Zero 服务器部署指南，完整覆盖从 Docker 安装、容器化启动、Apache 反向代理、SSL 证书、账号认证到域名解析、故障排查与日常维护的全流程。读完本文，你将能够在一台全新的 Linux VPS（AlmaLinux、Rocky、CentOS、Ubuntu、Debian 均可）上独立部署出 HTTPS 加密、可公网访问、支持多实例的 Agent Zero AI 框架，并理解底层容器与认证机制的实现原理。

一、前置条件：服务器、权限与软件依赖

1.1 服务器硬件要求

Agent Zero 以 Docker 容器方式运行，资源占用取决于实际承载的任务（代码执行、浏览器操作、文档检索等）。官方部署经验给出的基线如下：

说明：以上为社区部署经验值。实际内存占用与任务复杂度强相关，若同时启用浏览器自动化、向量检索等重负载插件，建议按推荐档位配置。

1.2 必备访问权限

• 服务器root 或 sudo权限；
• SSH访问（建议使用非默认端口，降低被扫描爆破的风险）；
• 具备DNS 控制权的域名或子域名；
• SSL 证书（Let's Encrypt 免费证书或商业证书均可）。

1.3 软件依赖清单

• Docker Engine 24.0+（含docker-compose-plugin）；
• Apache 2.4+，需要以下模块：mod_proxy、mod_proxy_http、mod_proxy_wstunnel、mod_ssl、mod_rewrite；
• curl、git（可选工具，用于诊断与后续维护）。

Apache 的 WebSocket 隧道模块mod_proxy_wstunnel是硬性依赖——Agent Zero 的实时交互（聊天流式响应、任务状态推送等）依赖 WebSocket 长连接，缺少该模块将导致实时功能失效（详见后文"WebSocket 验证"与"故障排查"章节）。

二、Docker 安装：三种方式与安装验证

[!NOTE] 更全面的 Docker 安装说明与替代方案，可参见主安装指南的 Linux Installation 章节。

方法 A：Debian/Ubuntu 系

# 更新软件包索引 apt-get update # 安装前置依赖 apt-get install -y ca-certificates curl gnupg # 添加 Docker 官方 GPG 密钥 install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg chmod a+r /etc/apt/keyrings/docker.gpg # 配置 Docker 软件源（按发行版代号自动匹配） echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker 引擎与 Compose 插件 apt-get update apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 开机自启并启动 systemctl enable docker systemctl start docker

方法 B：AlmaLinux/Rocky/CentOS/RHEL 系

# 安装插件核心 dnf -y install dnf-plugins-core # 添加 Docker 仓库（AlmaLinux/Rocky 复用 CentOS 仓库） dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # 安装 Docker 引擎与 Compose 插件 dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 开机自启并启动 systemctl enable docker systemctl start docker

方法 C：通用一键脚本

⚠️注意：一键脚本并非对所有发行版都可靠（例如在 AlmaLinux 上可能失败），生产环境建议优先使用官方仓库方式。

curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh systemctl enable docker systemctl start docker

验证 Docker 安装

docker --version docker run hello-world

docker run hello-world能正常输出欢迎信息并退出，说明守护进程、镜像拉取链路均正常。

三、Agent Zero 容器部署：目录、环境变量与启动

Step 1：创建实例目录结构

Agent Zero 的持久化数据全部落在宿主机目录中，容器只是无状态运行层。建议按实例隔离：

# 实例名与安装路径 A0_NAME="a0-instance" # 改为你的实例名 A0_PATH="/opt/${A0_NAME}" # 创建目录 mkdir -p ${A0_PATH} mkdir -p ${A0_PATH}/work_dir mkdir -p ${A0_PATH}/memory mkdir -p ${A0_PATH}/logs

各目录职责：work_dir/存放 Agent 工作文件，memory/存放 Agent 记忆数据，logs/存放实例日志。

Step 2：创建环境配置文件.env

# 生成带认证信息的 .env 文件 cat > ${A0_PATH}/.env << 'EOF' # Agent Zero Configuration # Authentication (REQUIRED for web access) AUTH_LOGIN=your_username_here AUTH_PASSWORD=your_secure_password_here # Optional: Additional configuration # See Agent Zero documentation for all options EOF

⚠️关键提醒：AUTH_LOGIN是用户名，不是布尔开关！

• ✅ 正确写法：AUTH_LOGIN=admin
• ❌ 错误写法：AUTH_LOGIN=true

源码印证：在 helpers/dotenv.py 中，KEY_AUTH_LOGIN = "AUTH_LOGIN"、KEY_AUTH_PASSWORD = "AUTH_PASSWORD"，容器启动后 Web 界面登录校验正是通过 helpers/login.py 从.env中读取这两个键的值；helpers/settings.py 中也是用同样的键读取用户名与密码参与校验。把AUTH_LOGIN误配成true，会导致登录名变成字符串 "true"，无法通过认证。

Step 3：选择宿主机端口

容器内部监听 80 端口（Web 界面由容器内进程承载），宿主端口按需映射。仓库自带的 docker/run/docker-compose.yml 也采用"50080:80"的映射约定，与本文档推荐的端口规范完全一致。

Step 4：拉取镜像并运行容器

# 设置变量 A0_NAME="a0-instance" A0_PATH="/opt/${A0_NAME}" A0_PORT="50080" # 拉取最新镜像 docker pull agent0ai/agent-zero:latest # 运行容器 docker run -d --name ${A0_NAME} --restart unless-stopped -p ${A0_PORT}:80 -v ${A0_PATH}/.env:/a0/.env -v ${A0_PATH}/usr:/a0/usr agent0ai/agent-zero:latest

参数解读：

• --restart unless-stopped：宿主机重启或 Docker 重启后自动拉起容器，除非被手动停止；
• -p ${A0_PORT}:80：宿主端口映射到容器内 80；
• -v ${A0_PATH}/.env:/a0/.env：挂载认证配置；
• -v ${A0_PATH}/usr:/a0/usr：挂载用户数据目录（工作目录、记忆、上传文件等都位于/a0/usr下，镜像内初始化脚本 docker/run/fs/exe/initialize.sh 会显式创建/a0/usr/uploads以保证上传功能可用）。

容器内部结构（源码佐证）：从 docker/run/Dockerfile 可以看出，镜像声明了EXPOSE 22 80 9000-9009，即容器内除 Web（80）外还包含 SSH（22）与附加服务端口；启动入口为CMD ["/exe/initialize.sh", "$BRANCH"]，该脚本负责提升打开文件数上限、恢复持久化配置并移交supervisord托管各服务。supervisord配置（docker/run/fs/etc/supervisor/conf.d/supervisord.conf）同时管理 sshd、cron、searxng 搜索服务、UI 主进程与隧道 API 进程——这解释了为什么容器内是一个"多服务"运行时，反向代理只需要转发 80 端口即可。

Step 5：验证容器

# 确认容器运行 docker ps | grep ${A0_NAME} # 查看日志 docker logs ${A0_NAME} # 测试本机访问 curl -I http://127.0.0.1:${A0_PORT}/

启用认证后，预期响应为HTTP/1.1 302 FOUND，且响应头包含Location: /login——即未登录访问会被重定向到登录页。

四、Apache 反向代理配置

4.1 启用所需模块

# Debian/Ubuntu a2enmod proxy proxy_http proxy_wstunnel ssl rewrite headers systemctl restart apache2 # AlmaLinux/CentOS（通常已预加载） httpd -M | grep -E "proxy|rewrite|ssl"

4.2 标准 Apache 配置（Debian/Ubuntu）

创建/etc/apache2/sites-available/a0-instance.conf：

# Agent Zero Reverse Proxy Configuration # Instance: a0-instance # Domain: a0.example.com # HTTP - 重定向到 HTTPS <VirtualHost *:80> ServerName a0.example.com ServerAlias www.a0.example.com RewriteEngine On RewriteCond %{HTTPS} off RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] </VirtualHost> # HTTPS - 反向代理到容器 <VirtualHost *:443> ServerName a0.example.com ServerAlias www.a0.example.com ServerAdmin webmaster@example.com # SSL 配置 SSLEngine on SSLCertificateFile /path/to/certificate.crt SSLCertificateKeyFile /path/to/private.key SSLCertificateChainFile /path/to/chain.crt # 反向代理配置 ProxyPreserveHost On ProxyPass / http://127.0.0.1:50080/ ProxyPassReverse / http://127.0.0.1:50080/ # WebSocket 支持（实时功能必需） RewriteEngine On RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L] # 日志 ErrorLog ${APACHE_LOG_DIR}/a0-instance.error.log CustomLog ${APACHE_LOG_DIR}/a0-instance.access.log combined </VirtualHost>

关键点解读：

• ProxyPreserveHost On：把客户端原始Host头透传给容器，确保重定向与内部 URL 生成正确；
• ProxyPass / http://127.0.0.1:50080/：所有 HTTP 流量代理到容器 80 端口；
• WebSocket 三条规则：当请求头带Upgrade: websocket且Connection: upgrade时，将连接升级为ws://隧道转发——Agent Zero 的实时聊天/流式响应依赖/ws端点（见 helpers/ws.py 的 WebSocket 实现），缺少这三行会导致前端连接失败。

启用配置并重载：

a2ensite a0-instance.conf apache2ctl configtest systemctl reload apache2

4.3 DirectAdmin 环境的 Apache 配置（AlmaLinux/CentOS）

Option A：使用 httpd-includes.conf（推荐）

编辑/etc/httpd/conf/extra/httpd-includes.conf：

# Agent Zero Proxy Configuration # Instance: a0-instance # Domain: a0.example.com # 注意：DirectAdmin 环境下必须使用具体 IP，不能使用通配符 <VirtualHost YOUR_SERVER_IP:80> ServerName a0.example.com ServerAlias www.a0.example.com RewriteEngine On RewriteCond %{HTTPS} off RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] </VirtualHost> <VirtualHost YOUR_SERVER_IP:443> ServerName a0.example.com ServerAlias www.a0.example.com ServerAdmin webmaster@example.com SSLEngine on # DirectAdmin SSL 证书路径（按用户与域名调整） SSLCertificateFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.cert.combined SSLCertificateKeyFile /usr/local/directadmin/data/users/USERNAME/domains/example.com.key ProxyPreserveHost On ProxyPass / http://127.0.0.1:50080/ ProxyPassReverse / http://127.0.0.1:50080/ # WebSocket 支持 RewriteEngine On RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L] ErrorLog /var/log/httpd/domains/a0.example.com.error.log CustomLog /var/log/httpd/domains/a0.example.com.access.log combined </VirtualHost>

⚠️DirectAdmin 环境的重要注意事项：

• 必须使用具体 IP 地址（如192.168.1.100:443），不能使用*:443；
• 绑定具体 IP 的 vhost 优先级高于 DirectAdmin 自动生成的 vhost，可避免被覆盖；
• SSL 证书统一存放在/usr/local/directadmin/data/users/USERNAME/domains/。

Option B：独立 conf.d 文件

如果 Apache 主配置已包含conf.d目录：

# 检查 conf.d 是否被包含 grep 'conf.d' /etc/httpd/conf/httpd.conf # 若未包含，在 directadmin-vhosts.conf 之前加入： sed -i '/Include conf\/extra\/directadmin-vhosts.conf/i Include conf.d/*.conf' /etc/httpd/conf/httpd.conf # 创建独立配置 mkdir -p /etc/httpd/conf.d cat > /etc/httpd/conf.d/httpd-vhosts-a0.conf << 'EOF' # 你的 vhost 配置（同 Option A） EOF

4.4 验证并重启 Apache

# 测试配置语法 httpd -t # AlmaLinux/CentOS apachectl -t # 备选 apache2ctl -t # Debian/Ubuntu # 重启 systemctl restart httpd # AlmaLinux/CentOS systemctl restart apache2 # Debian/Ubuntu

五、SSL/TLS 配置：三种获取证书的方式

Option A：Let's Encrypt + Certbot

# 安装 Certbot # Debian/Ubuntu: apt-get install certbot python3-certbot-apache # AlmaLinux/CentOS: dnf install certbot python3-certbot-apache # 签发证书（自动改写 Apache 配置） certbot --apache -d a0.example.com -d www.a0.example.com # 验证自动续期（通常为自动，但需确认） certbot renew --dry-run

Option B：DirectAdmin Auto-SSL

使用 DirectAdmin 时，SSL 通常由其自动管理：

1. 在 DirectAdmin 中创建域名/子域名；
2. 为该域名启用 "SSL"；
3. DirectAdmin 会自动申请 Let's Encrypt 证书；
4. 证书存放于/usr/local/directadmin/data/users/USERNAME/domains/。

Option C：手动/商业证书

mkdir -p /etc/ssl/a0 chmod 700 /etc/ssl/a0 # 复制证书文件 cp certificate.crt /etc/ssl/a0/ cp private.key /etc/ssl/a0/ cp chain.crt /etc/ssl/a0/ # 如有证书链 chmod 600 /etc/ssl/a0/*

私钥权限收紧到600、目录权限700，避免其他系统用户读取私钥。手动证书不参与自动续期，需自行在证书到期前更新并重载 Apache。

六、认证设置：AUTH_LOGIN / AUTH_PASSWORD 详解

6.1 认证变量速查

⚠️最常见错误：AUTH_LOGIN是用户名，不是启用认证的布尔开关！

底层机制：helpers/dotenv.py 定义了两个键名常量，容器内的 UI 服务启动时通过 helpers/settings.py 将AUTH_LOGIN、AUTH_PASSWORD注入前端设置（密码以占位符形式返回，不泄露明文）；登录请求由 helpers/login.py 完成比对。因此认证的开关状态由这两个变量是否为空决定——两者都为空时认证关闭，任一非空即启用认证。

6.2 设置认证

# 编辑 .env 文件 vi /opt/a0-instance/.env # 添加/更新以下内容： AUTH_LOGIN=your_username AUTH_PASSWORD=your_secure_password # 重启容器使配置生效 docker restart a0-instance

6.3 密码要求

• 建议最少8 个字符；
• 支持特殊字符（需正确转义）；
• 避免在密码中使用这些字符：' " \$（或仔细转义）——因为.env` 由 shell 解析，未转义的特殊字符可能截断配置项。

6.4 关闭认证（不推荐）

仅用于本地/开发环境：

# 注释或删除 .env 中的两行： # AUTH_LOGIN= # AUTH_PASSWORD= docker restart a0-instance

⚠️ 公网环境关闭认证意味着任何人都能访问你的 Agent Zero 实例，可被利用执行任意任务，务必仅在可信内网使用。

七、域名与 DNS 设置

7.1 DNS 记录

为服务器创建 A 记录：

7.2 DirectAdmin 子域名设置

1. 登录 DirectAdmin；
2. 进入：Domain Setup→ 选择域名 →Subdomain Management；
3. 创建子域名（如a0）；
4. 注意：Apache 代理配置会覆盖该子域名的默认 DocumentRoot。

7.3 验证 DNS 生效

# 检查 DNS 解析 dig a0.example.com +short nslookup a0.example.com # 应返回你的服务器 IP

TTL 300 秒意味着最长约 5 分钟内全球 DNS 缓存会收敛到新记录，若立即测试不通过可稍候再试。

八、验证与测试：上线前的完整检查清单

8.1 分步验证

# 1. 确认容器运行 docker ps | grep a0-instance # 2. 检查容器日志有无错误 docker logs a0-instance --tail 50 # 3. 测试容器本机访问 curl -I http://127.0.0.1:50080/ # 预期：HTTP/1.1 302 FOUND, Location: /login # 4. 校验 Apache 配置 httpd -t # 或 apache2ctl -t # 5. 验证 Apache 正确代理 curl -I http://127.0.0.1:80 -H "Host: a0.example.com" curl -Ik https://127.0.0.1:443 -H "Host: a0.example.com" # 6. 测试外部 HTTPS 访问 curl -I https://a0.example.com/ # 预期：HTTP/2 302 with Location: /login # 7. 验证登录页加载 curl -s https://a0.example.com/login | grep -i "<title>" # 预期：<title>Login - Agent Zero</title>

8.2 WebSocket 验证

# 安装 wscat（如未安装） npm install -g wscat # 测试 WebSocket 连接 wscat -c wss://a0.example.com/ws

能成功建立连接并保持（不立即断开），说明mod_proxy_wstunnel与 vhost 中的 WebSocket 重写规则均生效。该/ws端点是前端与后端实时通信的通道，对应仓库中的 helpers/ws.py 及 WebSocket 相关基础设施。

九、故障排查：常见问题速诊

问题 1：登录提示 "Invalid Credentials"

原因：.env配置错误。

修复：

# 检查容器内的 .env docker exec a0-instance cat /a0/.env # 确保格式为： # AUTH_LOGIN=username （不是 AUTH_LOGIN=true） # AUTH_PASSWORD=password # 修复后重启 docker restart a0-instance

问题 2：403 Forbidden

原因：DirectAdmin 的 vhost 覆盖了自定义代理配置。

修复：

# 检查 vhost 顺序 httpd -S 2>&1 | grep your-domain # 确保自定义配置在 directadmin-vhosts.conf 之前加载 # 使用具体 IP 绑定（如 192.168.1.1:443），不要用通配符（*:443） # 重启 Apache systemctl restart httpd

问题 3：502 Bad Gateway

原因：容器未运行或端口不匹配。

修复：

# 检查容器状态 docker ps -a | grep a0-instance # 若已停止，查看日志定位原因 docker logs a0-instance # 重启容器 docker start a0-instance # 确认端口绑定 netstat -tlnp | grep 50080

问题 4：504 Gateway Timeout

原因：容器过载或无响应（常见于大模型推理、重型任务占用内存）。

修复：

# 查看容器资源占用 docker stats a0-instance --no-stream # 重启容器 docker restart a0-instance # 检查宿主机内存 free -h

问题 5：WebSocket 连接失败

原因：vhost 缺少 WebSocket 代理规则。

修复：确保 vhost 配置中包含以下内容：

RewriteEngine On RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) ws://127.0.0.1:50080/$1 [P,L]

问题 6：容器无法启动

原因：端口冲突或 Docker 异常。

修复：

# 检查端口占用 netstat -tlnp | grep 50080 # 移除冲突容器 docker rm -f conflicting-container # 检查 Docker 守护进程 systemctl status docker journalctl -u docker --since "1 hour ago"

问题 7：修改 .env 不生效

原因：环境变量在容器启动时加载，需重启容器。

修复：

docker restart a0-instance # 验证环境变量已加载 docker exec a0-instance cat /a0/.env

十、维护与更新

10.1 升级 Agent Zero

# 拉取最新镜像 docker pull agent0ai/agent-zero:latest # 停止并移除旧容器（数据保存在卷中，不会丢失） docker stop a0-instance docker rm a0-instance # 用相同参数重建 docker run -d --name a0-instance --restart unless-stopped -p 50080:80 -v /opt/a0-instance/.env:/a0/.env -v /opt/a0-instance/usr:/a0/usr agent0ai/agent-zero:latest

注意：升级前建议先备份（见下节）。由于work_dir/、memory/等数据都落在/opt/a0-instance/usr的挂载卷中，删除容器不会丢失数据；.env挂载在/a0/.env，同样保留。

10.2 备份策略

# 备份全部实例数据 tar -czvf a0-backup-$(date +%Y%m%d).tar.gz /opt/a0-instance/ # 关键备份项： # - /opt/a0-instance/.env （配置，含认证信息，注意保密） # - /opt/a0-instance/memory/ （Agent 记忆数据） # - /opt/a0-instance/work_dir/ （工作文件）

10.3 监控

# 容器健康状态 docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}" # 实时日志（最近 100 行并跟随） docker logs --tail 100 -f a0-instance # 资源占用 docker stats a0-instance

10.4 Docker 清理

# 清理未使用的镜像 docker image prune -f # 清理所有未使用的 Docker 资源 docker system prune -f

定期清理可避免历史镜像、悬空卷堆积占用磁盘；docker system prune -f会一并删除停止的容器与未使用的网络，执行前请确认没有需要保留的临时容器。

十一、速查表

11.1 常用命令

# 容器管理 docker start a0-instance docker stop a0-instance docker restart a0-instance docker logs a0-instance docker exec -it a0-instance bash # Apache 管理 systemctl restart httpd # RHEL/AlmaLinux systemctl restart apache2 # Debian/Ubuntu httpd -t # 测试配置 # 快速诊断 docker ps | grep a0 curl -I https://your-domain.com/login

11.2 标准路径

11.3 标准端口

11.4.env模板

# Agent Zero Configuration Template # Copy and customize for each instance # Authentication (REQUIRED for production) AUTH_LOGIN=your_username AUTH_PASSWORD=your_secure_password # Optional: Additional settings # Refer to Agent Zero documentation for all options

十二、附录：同一服务器多实例部署

在一台服务器上运行多个彼此隔离的 Agent Zero 实例：

# 实例 1：a0-primary，端口 50080 mkdir -p /opt/a0-primary # ... 创建 .env，在 50080 端口运行容器 # 实例 2：a0-dev，端口 50081 mkdir -p /opt/a0-dev # ... 创建 .env，在 50081 端口运行容器 # 实例 3：a0-backup，端口 50082 mkdir -p /opt/a0-backup # ... 创建 .env，在 50082 端口运行容器

每个实例都需要独立配置：

• 唯一的容器名；
• 唯一的宿主机端口；
• 独立的数据目录；
• 独立的域名/子域名；
• 独立的 Apache vhost 配置。

仓库自带的 docker/run/docker-compose.yml 还展示了两个进阶选项，可作为单实例/多实例部署的补充参考：ulimits.nofile将容器内打开文件数上限提升至 65535（与镜像内初始化脚本 docker/run/fs/exe/initialize.sh 通过A0_NOFILE_LIMIT环境变量提升文件句柄上限的机制对应，高并发任务下可避免 "too many open files"），以及extra_hosts将host.docker.internal指向宿主机网关，便于容器内服务访问宿主机上的资源。

本文整理自 Agent Zero 社区在 DirectAdmin 与标准 Linux 环境中的成功部署经验（由 @hurtdidit 在 A0 Community 贡献），并结合仓库源码（docker/run/Dockerfile、docker/run/docker-compose.yml、docker/run/fs/exe/initialize.sh、helpers/dotenv.py、helpers/login.py、helpers/settings.py）交叉验证。部署环境不同可能导致细节差异，请以你的实际系统为准。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero