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 VPSAlmaLinux、Rocky、CentOS、Ubuntu、Debian 均可上独立部署出 HTTPS 加密、可公网访问、支持多实例的 Agent Zero AI 框架并理解底层容器与认证机制的实现原理。一、前置条件服务器、权限与软件依赖1.1 服务器硬件要求Agent Zero 以 Docker 容器方式运行资源占用取决于实际承载的任务代码执行、浏览器操作、文档检索等。官方部署经验给出的基线如下需求项最低配置推荐配置内存 RAM2 GB4 GB存储 Storage20 GB50 GBCPU1 vCPU2 vCPU操作系统Linux64 位AlmaLinux 9、Ubuntu 22.04网络静态 IP独立 IP 且配置反向 DNS说明以上为社区部署经验值。实际内存占用与任务复杂度强相关若同时启用浏览器自动化、向量检索等重负载插件建议按推荐档位配置。1.2 必备访问权限服务器root 或 sudo权限SSH访问建议使用非默认端口降低被扫描爆破的风险具备DNS 控制权的域名或子域名SSL 证书Lets Encrypt 免费证书或商业证书均可。1.3 软件依赖清单Docker Engine 24.0含docker-compose-pluginApache 2.4需要以下模块mod_proxy、mod_proxy_http、mod_proxy_wstunnel、mod_ssl、mod_rewritecurl、git可选工具用于诊断与后续维护。Apache 的 WebSocket 隧道模块mod_proxy_wstunnel是硬性依赖——Agent Zero 的实时交互聊天流式响应、任务状态推送等依赖 WebSocket 长连接缺少该模块将导致实时功能失效详见后文WebSocket 验证与故障排查章节。二、Docker 安装三种方式与安装验证[!NOTE] 更全面的 Docker 安装说明与替代方案可参见主安装指南的 Linux Installation 章节。方法 ADebian/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 ar /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方法 BAlmaLinux/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-worlddocker run hello-world能正常输出欢迎信息并退出说明守护进程、镜像拉取链路均正常。三、Agent Zero 容器部署目录、环境变量与启动Step 1创建实例目录结构Agent Zero 的持久化数据全部落在宿主机目录中容器只是无状态运行层。建议按实例隔离# 实例名与安装路径 A0_NAMEa0-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_LOGINyour_username_here AUTH_PASSWORDyour_secure_password_here # Optional: Additional configuration # See Agent Zero documentation for all options EOF⚠️关键提醒AUTH_LOGIN是用户名不是布尔开关✅ 正确写法AUTH_LOGINadmin❌ 错误写法AUTH_LOGINtrue源码印证在 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选择宿主机端口端口适用场景50080标准/推荐端口配合反向代理使用50081、50082…同一台服务器上的其他实例80直接访问不推荐用于生产容器内部监听 80 端口Web 界面由容器内进程承载宿主端口按需映射。仓库自带的 docker/run/docker-compose.yml 也采用50080:80的映射约定与本文档推荐的端口规范完全一致。Step 4拉取镜像并运行容器# 设置变量 A0_NAMEa0-instance A0_PATH/opt/${A0_NAME} A0_PORT50080 # 拉取最新镜像 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即容器内除 Web80外还包含 SSH22与附加服务端口启动入口为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|ssl4.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,R301] /VirtualHost # HTTPS - 反向代理到容器 VirtualHost *:443 ServerName a0.example.com ServerAlias www.a0.example.com ServerAdmin webmasterexample.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 apache24.3 DirectAdmin 环境的 Apache 配置AlmaLinux/CentOSOption 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,R301] /VirtualHost VirtualHost YOUR_SERVER_IP:443 ServerName a0.example.com ServerAlias www.a0.example.com ServerAdmin webmasterexample.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 EOF4.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 ALets 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-runOption BDirectAdmin Auto-SSL使用 DirectAdmin 时SSL 通常由其自动管理在 DirectAdmin 中创建域名/子域名为该域名启用 SSLDirectAdmin 会自动申请 Lets Encrypt 证书证书存放于/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登录用户名AUTH_LOGINadminAUTH_PASSWORD登录密码AUTH_PASSWORDSecurePass123!⚠️最常见错误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_LOGINyour_username AUTH_PASSWORDyour_secure_password # 重启容器使配置生效 docker restart a0-instance6.3 密码要求建议最少8 个字符支持特殊字符需正确转义避免在密码中使用这些字符 \$或仔细转义——因为.env 由 shell 解析未转义的特殊字符可能截断配置项。6.4 关闭认证不推荐仅用于本地/开发环境# 注释或删除 .env 中的两行 # AUTH_LOGIN # AUTH_PASSWORD docker restart a0-instance⚠️ 公网环境关闭认证意味着任何人都能访问你的 Agent Zero 实例可被利用执行任意任务务必仅在可信内网使用。七、域名与 DNS 设置7.1 DNS 记录为服务器创建 A 记录类型名称值TTLAa0YOUR_SERVER_IP300Awww.a0YOUR_SERVER_IP3007.2 DirectAdmin 子域名设置登录 DirectAdmin进入Domain Setup→ 选择域名 →Subdomain Management创建子域名如a0注意Apache 代理配置会覆盖该子域名的默认 DocumentRoot。7.3 验证 DNS 生效# 检查 DNS 解析 dig a0.example.com short nslookup a0.example.com # 应返回你的服务器 IPTTL 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 # 预期titleLogin - Agent Zero/title8.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_LOGINusername 不是 AUTH_LOGINtrue # AUTH_PASSWORDpassword # 修复后重启 docker restart a0-instance问题 2403 Forbidden原因DirectAdmin 的 vhost 覆盖了自定义代理配置。修复# 检查 vhost 顺序 httpd -S 21 | grep your-domain # 确保自定义配置在 directadmin-vhosts.conf 之前加载 # 使用具体 IP 绑定如 192.168.1.1:443不要用通配符*:443 # 重启 Apache systemctl restart httpd问题 3502 Bad Gateway原因容器未运行或端口不匹配。修复# 检查容器状态 docker ps -a | grep a0-instance # 若已停止查看日志定位原因 docker logs a0-instance # 重启容器 docker start a0-instance # 确认端口绑定 netstat -tlnp | grep 50080问题 4504 Gateway Timeout原因容器过载或无响应常见于大模型推理、重型任务占用内存。修复# 查看容器资源占用 docker stats a0-instance --no-stream # 重启容器 docker restart a0-instance # 检查宿主机内存 free -h问题 5WebSocket 连接失败原因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-instance10.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/login11.2 标准路径组件路径实例数据目录/opt/a0-instance/环境配置文件/opt/a0-instance/.env记忆存储/opt/a0-instance/memory/工作目录/opt/a0-instance/work_dir/Apache 配置标准/etc/apache2/sites-available/Apache 配置DirectAdmin/etc/httpd/conf/extra/httpd-includes.confDirectAdmin SSL 证书/usr/local/directadmin/data/users/USER/domains/11.3 标准端口端口用途50080第一个 A0 实例50081第二个 A0 实例50082第三个 A0 实例80HTTP重定向到 HTTPS443HTTPS主访问入口11.4.env模板# Agent Zero Configuration Template # Copy and customize for each instance # Authentication (REQUIRED for production) AUTH_LOGINyour_username AUTH_PASSWORDyour_secure_password # Optional: Additional settings # Refer to Agent Zero documentation for all options十二、附录同一服务器多实例部署在一台服务器上运行多个彼此隔离的 Agent Zero 实例# 实例 1a0-primary端口 50080 mkdir -p /opt/a0-primary # ... 创建 .env在 50080 端口运行容器 # 实例 2a0-dev端口 50081 mkdir -p /opt/a0-dev # ... 创建 .env在 50081 端口运行容器 # 实例 3a0-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考