企业官网建设流程全解析

Antigravity 这套工具在我们团队落地跑了大半年，前前后后帮我管住了几十个定时任务和批量计算。说实话，刚接手的时候踩坑不少，光“怎么又 403”“容器怎么起不来”这类问题就被同事问过不下二十次。最近看社区里问 Antigravity 部署的人越来越多，很多新手卡在几个很隐蔽的细节上，所以我把从部署到日常维护的完整链路整理了一遍，重点讲三个最容易翻车的坑。这篇文章适合刚接触 Antigravity、准备在生产环境正式使用的同学，也适合已经在用但时不时被权限和资源问题折磨的人。我会先拆解整体设计思路，再讲保姆级部署步骤，最后给出一份可以直接照着排查的问题速查清单。

1. 为什么选 Antigravity：核心思路与架构拆解

1.1 Antigravity 解决的核心问题

Antigravity 本质上是一个面向批处理场景的轻量级任务调度与执行平台。我们团队之前用的是最原始的 crontab 加一堆 shell 脚本，短时间跑三五个任务还行，一旦任务多到上百个，各种依赖环境冲突、日志丢失、重试机制缺失的问题就开始集中爆发。Antigravity 最核心的价值在于把“任务定义、执行环境、调度策略、结果反馈”四件事解耦了。

举个例子，以前我要跑一个 Python 数据清洗任务，得在服务器上装对应版本的 Python 和依赖库，换一台机器就得重新来一遍。在 Antigravity 里，每个任务都可以声明自己的容器镜像，执行时由平台自动拉起隔离环境，跑完自动回收。你不再需要关心“这个任务跑在哪个机器、哪个环境”，只需要关心“任务内容是什么、什么时候触发”。

另一个解决得非常好的痛点是失败恢复。以前的脚本一旦半路崩了，要么靠人工发现，要么靠另一个监控脚本去轮询日志。Antigravity 自带重试和告警钩子，任务失败时可以按预设策略自动重跑，还能把结果推送到内部消息系统。这对我们这种“凌晨跑数据、早上要看报告”的场景特别友好。

1.2 整体架构与模块划分

Antigravity 的架构并没有多复杂，核心由四部分组成：

• 控制面（Controller）：负责接收任务请求、解析调度策略、下发执行指令。
• 执行节点（Worker）：真正跑任务的地方。每个任务会以容器方式隔离运行，Worker 负责拉取镜像、启动容器、回收资源。
• 存储层（Storage）：保存任务定义、历史执行记录、调度状态。一般推荐 PostgreSQL，数据可靠性比默认的 SQLite 好很多。
• 网关层（Gateway）：提供 Web 控制台和 REST API，也是用户日常操作最多的入口。

这四部分可以全部部署在一台机器上，也可以把控制面和 Worker 拆开部署。小团队一开始用单机模式完全足够，随着任务量增长再逐步拆分。拆分的好处是执行节点的资源可以独立扩容，比如你有两台高配机器专门跑重计算任务，控制面只需要一个低配实例就能撑住调度压力。

1.3 三种部署方式的取舍

根据团队规模和场景差异，我见过三种主流的部署方式：

我在生产环境用的就是 docker-compose 方案，搭配每日自动备份数据库。不要小看这个“简单方案”，我们高峰期日均执行 3000 多个任务，单机模式依旧稳定。选 K8s 之前，先在单机上把业务跑透，再把控制面和 Worker 平滑迁移过去，这是我认为最稳妥的路径。

2. 部署前的三项关键准备与“三个大坑”预警

2.1 大坑一：权限配置不是“能用就行”，403 多半出在这里

很多人第一次启动 Antigravity 后，访问 Web 控制台直接看到一个 403 Forbidden，第一反应是“是不是端口不对”“是不是防火墙拦截”。我当初也排查了半天，最后发现问题出在容器启动时的工作目录和挂载卷权限上。

Antigravity 默认不会以 root 身份运行控制面进程，这是出于安全考虑的正确设计。但如果你把宿主机上某个目录挂载进容器作为数据目录，而这个目录的属主和属组不是容器内运行用户，那应用进程就没法正常读写。权限不够时，网关层在初始化阶段会报 403，而不是一个清晰的“权限不足”提示。

具体表现是：日志里可能只有一行permission denied，但浏览器里呈现的是 403。排查思路很简单，先确认宿主机挂载目录的属主：

ls -lnd /data/antigravity

然后去 Antigravity 镜像里查一下默认运行用户的 uid：

docker run --rm antigravity/controller:2.3.1 id

一般镜像会用 uid 1000，而宿主机的 /data/antigravity 如果被 root 占用，权限就不匹配。解决办法不是粗暴地chmod 777，而是把目录属主改成容器内的 uid：

mkdir -p /data/antigravity chown -R 1000:1000 /data/antigravity

这里最值得记住的是：任何配置变更前，先确认进程跑在什么身份下，再给对应身份授权。生产环境尤其别贪图方便给宽泛权限，避免埋下越权隐患。

2.2 大坑二：依赖版本和镜像标签对不上

Antigravity 第二个高频坑是镜像版本与配置文件的 schema 对不上。很多新手从文档里复制了一份docker-compose.yml，里面写着image: antigravity/controller:latest，然后满心欢喜地去跑，结果服务起来后接口返回一大堆莫名其妙的字段错误，甚至启动日志里直接提示某个配置项无法识别。

根因是latest标签并不是一个稳定的版本标识。昨天拉到的可能还是 2.2.x，今天再拉就可能变成了 2.3.x，而 2.3.x 的配置结构有调整。一旦控制前版本和配置文件 schema 不匹配，轻则告警刷屏，重则网关起不来。

我从那次踩坑之后定了一条铁规矩：部署文件里永远写具体版本号，不写 latest。镜像标签锁定后，配置文件也跟着锁定，两者一一对应。比如：

image: antigravity/controller:2.3.1 image: antigravity/worker:2.3.1 environment: ANTIGRAVITY_SCHEMA_VERSION: "2.3"

如果你想升级版本，先看官方发布的迁移说明，再改镜像标签和配置，不要同一时间既换镜像又改配置。出问题时变量太多，很难定位。

另外，数据库 Schema 的版本也要一起考虑。Antigravity 启动时会对存储层做迁移检查，如果你的数据库是旧的，新的控制面启动时会尝试自动迁移。这个自动迁移默认是开启的，但最好提前备份数据库，免得迁移过程中出现意外情况。

2.3 大坑三：资源限制没预留，任务一多直接 OOM 或排队打转

第三个坑和资源配额有关。Antigravity 的任务并发数默认取值比较乐观，也就是说如果你不设置任何 CPU 和内存限制，几个重任务同时跑起来就可能把宿主机的内存吃光，然后触发 OOM。更隐蔽的问题是任务调度器进入反复重试状态，表现为任务一直 pending，日志里没有任何明显报错。

我最早部署时也觉得“服务器配置多高都无所谓，任务跑完就释放了”，直到有一次夜里 12 点定时任务集中触发，16G 内存的机器瞬间被打满，连 SSH 都连不上。后来我养成了给每个任务组设定资源上限的习惯。

在任务配置里建议这样写：

resources: cpu: "0.5" memory: 1Gi timeout: 300

这里的cpu: 0.5表示最多占用半个核心，memory: 1Gi表示容器内存上限 1GB，timeout: 300表示单任务最多跑 5 分钟，超过主动终止并标记失败。这样做还有一个额外好处：某个任务写死循环时能被快速掐断，不会拖垮整个 Worker。

如果是在 docker-compose 里统一定义了 Worker 的资源池，可以给 Worker 容器本身预留合理的 limits。我曾经见过一个团队把所有任务都丢给同一个 Worker，也不设置全局 max_concurrency，结果并发一高，任务的排队时间比实际执行时间还长。合理配置应该是：

services: worker: deploy: resources: limits: cpus: "4" memory: 8Gi environment: ANTIGRAVITY_MAX_CONCURRENCY: "4"

MAX_CONCURRENCY=4的含义是同一时刻最多运行 4 个任务容器，配合单任务内存上限，整个 Worker 的内存峰值是可控的。

3. 保姆级实操：从零部署 Antigravity 并跑通第一个任务

3.1 准备目录结构和环境变量

不管用什么方式部署，我都建议先把目录结构规划好。下面这套是我目前正在用的，简单清晰：

/data/antigravity/ ├── compose/ │ └── docker-compose.yml ├── data/ │ ├── postgres/ │ └── artifacts/ ├── config/ │ └── antigravity.yaml └── logs/

环境变量不要散落在命令行里，统一写进.env文件，这样换机器部署时只需携带一份环境配置。核心变量包括：

ANTIGRAVITY_DB_HOST=postgres ANTIGRAVITY_DB_PORT=5432 ANTIGRAVITY_DB_USER=antigravity ANTIGRAVITY_DB_PASSWORD=please-change-me ANTIGRAVITY_DATA_DIR=/data/antigravity/data ANTIGRAVITY_LOG_LEVEL=info

特别注意数据库密码。默认密码一定不能直接上生产环境，至少要改成随机生成的字符串。我见过不少团队把密码写死在 compose 文件里，然后整个仓库公开出去，这是非常危险的事。

3.2 编写 docker-compose 配置

我的生产环境 compose 文件长这样，你可以直接参考改改：

version: "3.8" services: postgres: image: postgres:15.4 container_name: antigravity-postgres restart: always environment: POSTGRES_DB: antigravity POSTGRES_USER: antigravity POSTGRES_PASSWORD: ${ANTIGRAVITY_DB_PASSWORD} volumes: - /data/antigravity/data/postgres:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U antigravity"] interval: 10s timeout: 3s retries: 5 controller: image: antigravity/controller:2.3.1 container_name: antigravity-controller restart: always depends_on: postgres: condition: service_healthy ports: - "8080:8080" env_file: - .env volumes: - /data/antigravity/config/antigravity.yaml:/etc/antigravity/antigravity.yaml:ro - /data/antigravity/data/artifacts:/data/artifacts - /data/antigravity/logs:/var/log/antigravity healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"] interval: 30s timeout: 5s retries: 3 worker: image: antigravity/worker:2.3.1 container_name: antigravity-worker restart: always depends_on: controller: condition: service_healthy env_file: - .env volumes: - /var/run/docker.sock:/var/run/docker.sock deploy: resources: limits: cpus: "4" memory: 8Gi environment: ANTIGRAVITY_MAX_CONCURRENCY: "4"

这里有个关键点：Worker 需要访问宿主机上的 Docker socket，这样才能动态拉起任务容器。如果你觉得直接挂载 socket 不够安全，可以通过更细粒度的权限控制来限制 Worker 的行为，但内部环境可以先这么跑起来。

3.3 初始化数据库与管理员账号

第一次启动前需要初始化数据库表结构。如果你的控制面镜像自带迁移命令，可以直接执行：

docker compose run --rm controller antigravity migrate

这条命令会读取antigravity.yaml里的数据库连接信息，自动建表。跑完之后再正式启动服务：

docker compose up -d

启动完成后，访问http://服务器IP:8080。首次进入会要求初始化管理员账号，这里我只提醒一点：邮箱和管理员密码一定要单独保管，不要用公司统一弱密码。Antigravity 的控制台权限级别很高，能删除历史记录、修改全局配置，一旦账号泄露影响很大。

初始化完成后，建议立刻创建一个只读账号给团队其他成员查看任务状态，管理员账号留在自己手里。日常运维用只读账号观察足够，变更操作才需要切到管理员。

3.4 创建第一个任务并验证调度

现在来跑通一个最简单的“Hello World”任务。在控制台的任务列表页面，新建一个任务：

• 名称填first-task
• 镜像选择busybox:1.36
• 命令填echo hello antigravity && sleep 2
• 调度方式选manual，先手动触发一次

保存后点击运行，等待几秒，刷新页面就能看到任务状态从pending变running，最后变为succeeded。点进执行记录，能看到完整的标准输出：

hello antigravity

这一步能跑通，说明核心链路已经通了。接下来可以尝试定时调度，比如每天凌晨两点执行：

schedule: cron: "0 2 * * *" timezone: "Asia/Shanghai"

这里时区一定要显式指定。Antigravity 默认使用 UTC 时间，如果你写一个0 2 * * *却不指定时区，那么实际执行时间是北京时间的早上八点。这个时间错位的坑太隐蔽了，我第一次用定时任务就踩过。

4. 常见问题排查技巧与自己的避坑心得

4.1 403 排查三步法

遇到 403 我一般按三步走，效率非常高：

第一步，确认是否权限问题。直接看日志里有没有permission denied或者forbidden关键字。

docker logs antigravity-controller --tail 200 | grep -i forbid

第二步，检查挂载目录权限。尤其是数据目录和配置文件目录，看属主属组对不对。这一步往往能解决八成问题。

第三步，验证配置文件是否被正确加载。Antigravity 控制台对配置文件的读取是严格模式，如果文件权限是 0644 且属主是 root，容器内非 root 用户可能读不到，然后对外表现为 403。把配置文件和挂载目录都统一成镜像内用户可读可写的状态就好了。

另外一个容易被忽略的细节：Nginx 或负载均衡器反代到 Antigravity 时，如果请求头里带了特殊的认证字段，而后端校验失败，也会返回 403。这种场景下可以先绕过负载均衡，直接访问后端端口，用来区分问题出在网关还是 Antigravity 本体。

4.2 任务一直 pending 的处理思路

任务一直 pending 通常分三种情况：

第一，并发数已经达到上限。Worker 配置了MAX_CONCURRENCY，任务是一个接一个排队执行的。这个时候不是系统卡死，而是任务在等资源。去 Worker 日志里看queue length就能确认。

第二，镜像拉取卡住。任务指定的镜像比较大，或者镜像仓库网络不稳定，Worker 会一直卡在拉镜像阶段。解决办法是提前把常用镜像拉到宿主机上，让任务容器直接使用本地镜像。

第三，调度器时间不同步。Antigravity 对任务下次执行时间的计算依赖服务器时钟。如果宿主机时间跳变，调度器可能误判任务还没到执行时间。这个案例比较少见，但我实际遇到过，最后用chronyc同步时间解决的。

我的经验是，先看任务详情页里的last_error字段，大多数情况下平台已经把失败原因写进去了。如果没有，再进 Worker 日志翻。不要一开始就重启服务，重启只会掩盖问题。

4.3 容器日志和数据目录的清理习惯

Antigravity 跑久了，日志和数据目录膨胀的速度比想象中快。我见过一个测试环境跑了两周，日志文件占了 40G 磁盘空间。无论你的宿主机空间多大，都应该给日志和数据目录做轮转。

可以参考下面这套配置：

# 每天凌晨清理超过 7 天的容器日志 find /data/antigravity/logs -name "*.log" -mtime +7 -delete # 清理任务执行产生的临时产物，只保留最近 3 天 find /data/antigravity/data/artifacts -mtime +3 -delete

如果你对历史执行记录有审计要求，临时产物不建议直接删除，而是定期打包到归档存储。但日志文件和个人开发环境的临时产物，该清就清，别等磁盘告警了再去处理。

还有一个好习惯是每次执行完一个批处理任务，顺手检查一下 PostgreSQL 的数据体积。Antigravity 会保存每次执行的状态和耗时，数据量大了之后，查询历史任务会明显变慢。可以定期清理掉已经标记为 succeeded 的旧记录，只保留最近的几百条用于回溯。

4.4 快速排查速查表

最后整理一张速查表，方便你对症下药。

这张表是我自己贴在工位上的，每次有人喊“任务跑不了了”，我先对照一遍，基本十分钟内能定位到问题。

最后再分享一个我个人的习惯：Antigravity 的控制台和 API 很强大，但越强大越要管住手。任何涉及全局配置的更改，先在一个非生产环境验证一遍，再同步到生产。我吃过一次亏：修改了一个全局环境变量，结果影响到了所有正在运行的任务，几十个任务全部重跑。从那以后，每次改配置前先快照数据库，改完观察半小时再继续做其他操作。

Antigravity 是一个能实实在在提升任务管理效率的平台，但它不是魔法。把权限、版本、资源这三件事想清楚，部署过程会顺畅得多。希望这篇教程能帮你少走弯路，一次就把环境跑起来。