1. 前置条件#

只需要 Docker。macOS 上装 Docker Desktop：

1
brew install --cask docker

装完打开一次 Docker Desktop，等鲸鱼图标变绿，确认命令能用：

1
docker version
2
docker compose version

docker compose（带空格）是 v2 插件，现在默认就是这个。不要再装 docker-compose（v1，已经废弃）。

2. 拉源码#

1
git clone https://github.com/mhtsec/ARTEX.git ~/tools/ARTEX
2
cd ~/tools/ARTEX

放在 ~/tools/ 下是我自己的习惯，路径随意，后面所有命令按这个路径写。

顺便说一句镜像的事：原镜像源 autumn27/artex 已经从 Docker Hub 删了，现在由作者维护成 mianhuatang11/artex。如果拉取失败，可以直接从纯源码本地构建（多阶段构建，无外部预编译依赖）：

1
docker compose build

代价是慢，前端 npm ci + Go 编译，第一次十几分钟很正常。

3. 写 .env#

1
cp .env.example .env

必须改的只有一行：

1
POSTGRES_PASSWORD=change-me-please

不想手敲就生成一个：

1
openssl rand -base64 18

其余的 LLM 相关（ANTHROPIC_API_KEY / OPENAI_API_KEY / ARTEX_LLM_*）都可以先留空，进 UI 里配。

⚠️ 这个密码一旦用于初始化数据库卷就改不动了（后面「常见问题」会讲为什么），第一次就定好。

4. 启动#

1
docker compose up -d

第一次要拉两个镜像，ARTEX 本体 2.37 GB，postgres:16-alpine 411 MB，看网速，国内建议先配好镜像加速。

启动顺序是 compose 文件里写死的：

1
depends_on:
2
  postgres:
3
    condition: service_healthy

也就是 postgres 的 healthcheck 通过之后才起 artex，不是简单的”先启动后启动”。所以 docker compose ps 里会先看到 postgres 变成 (healthy)，artex 才开始 Up。

5. 确认起来了#

1
docker compose ps

正常状态长这样：

1
NAME               IMAGE                        STATUS                   PORTS
2
artex-artex-1      mianhuatang11/artex:latest   Up 2 hours               0.0.0.0:8787->8787/tcp, 127.0.0.1:8788->8788/tcp
3
artex-postgres-1   postgres:16-alpine           Up 2 hours (healthy)     5432/tcp

再用 HTTP 确认一次，比 ps 更可信：

1
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8787/
2
# 200
3
curl -s http://127.0.0.1:8787/api/health
4
# 200

注意 /api/version 这种接口不带登录态会返回 {"error":"未授权"}，这是鉴权正常的表现，不是服务挂了。

6. 首次进入#

浏览器打开 **http://localhost:8787**，会自动跳到 /setup 设置管理员密码。

• 登录用户名固定是 ARTEX
• 密码以 bcrypt 哈希存进数据库 settings 表的 auth.password_hash

设完再去「LLM 配置」页填模型和 Key，否则 agent 能启动但不会思考。

1. 两个端口，不是一个#

compose 里是这么发布的：

1
ports:
2
  - "8787:8787"
3
  - "127.0.0.1:8788:8788"

8787 是前端 + API + SSE 实时活动流，绑 0.0.0.0，也就是同局域网的其他设备能访问。

8788 是流量录制代理（MITM，带 CA 存证），只绑 127.0.0.1，故意只让本机访问。

看到 8788 没对外开放不要以为是配错了，那是设计。也别为了”方便远程调试”把它改成 0.0.0.0——那等于把一台能解密 HTTPS 的代理挂到局域网上。

2. 数据存在三个地方#

关服务不会丢数据，前提是别碰这三个地方：

• pgdata 卷（Docker 命名卷 artex_pgdata，约 238 MB）：任务、资产图、探索图、设置、密码哈希。是最核心的一份。
• ./data 目录（bind mount 到容器的 /app/data，实测 2.2 GB）：会话记录、transcripts、流量包、证据文件。会随着使用快速膨胀，主要是 data/tasks 和 data/traffic。
• ./skills 目录：技能提示词，挂载进来是为了改完不用重建镜像。

容器本身是”用完就扔”的，这三处才是真实的资产。

3. 容器里跑的是 start.sh，不是 artex 本体#

镜像的入口是 start.sh，它是个守护脚本：

• 子进程退出码 0 → 用户正常停止，脚本退出
• 退出码 75 → 程序请求重启（页面上的”一键更新”靠这个换装）
• 其他 → 崩溃，退避 1/2/4…最多 60 秒后重拉

它还会把 SIGTERM 转发给 artex。因为 docker stop 只把信号发给 PID 1，也就是这个脚本，不转发的话 artex 收不到、做不了优雅关闭，10 秒后被 SIGKILL 硬杀，正在跑的任务直接断在半路。

这解释了后面实测里那个 Exited (0)：不是意外退出，是优雅关闭。

方式一：docker compose stop（推荐日常用）#

1
cd ~/tools/ARTEX
2
docker compose stop

实测耗时 0.9 秒，两个容器都是 Exited (0)：

1
Container artex-artex-1     Stopped
2
Container artex-postgres-1  Stopped

容器还在（docker compose ps -a 能看到），数据全留，重新开最快。

方式二：docker compose down#

1
docker compose down

删掉容器和网络，但保留 pgdata 卷和 ./data、./skills 这两个 bind mount。

什么时候用它：改了 docker-compose.yml（比如加减环境变量、改端口），需要让 compose 重新按新配置建容器。stop 之后再 up 用的是旧容器，新配置不生效。

方式三：docker compose down -v#

1
docker compose down -v

多了一个 -v，连 pgdata 卷一起删。

任务、资产、漏洞、账号密码，全都没了。只剩 ./data 里的现场文件，而数据库没了那些文件也读不出来。

这条命令唯一合适的场景是”我想彻底重来一遍”。手滑按到的代价是几天的工作量，建议打完 down 就停手，-v 单独敲。

方式四：直接退出 Docker Desktop 或关机#

关掉 Docker Desktop（菜单里 Quit），或者直接合盖关机。

效果上接近方式一：Docker 会先把运行中的容器停掉。区别是它不那么可控，正在跑的任务可能被打断。如果手上有任务在跑，先停任务，再 docker compose stop，最后退出 Docker。

第一步：确认 Docker 守护进程在跑#

这是很容易漏掉的一步。容器停着的时候执行 docker compose up -d，会得到：

1
Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
2
Is the docker daemon running?

macOS 上 Docker 跑在一个轻量虚拟机里，必须先把 Docker Desktop 打开：

1
open -a Docker

然后等它就绪（不是立刻可用，一般十几秒）：

1
until docker info >/dev/null 2>&1; do sleep 1; done; echo "docker ready"

第二步：进入项目目录，拉起来#

1
cd ~/tools/ARTEX
2
docker compose up -d

输出会体现依赖顺序：

1
Container artex-postgres-1  Starting
2
Container artex-postgres-1  Started
3
Container artex-postgres-1  Waiting
4
Container artex-postgres-1  Healthy
5
Container artex-artex-1     Starting
6
Container artex-artex-1     Started

实测从执行命令到 HTTP 返回 200，2 秒：

1
for i in $(seq 1 20); do
2
  code=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8787/)
3
  [ "$code" = "200" ] && echo "第 ${i} 秒就绪" && break
4
  sleep 1
5
done

第三步：三连确认#

1
docker compose ps                  # 两个 Up，postgres 带 (healthy)
2
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8787/api/health
3
docker compose logs --tail 20 artex

ps 看进程、curl 看端口、logs 看有没有报错。三个都对上才算真起来了。

说明：start / restart / up -d 的区别#

三个命令都能”起来”，但语义不同，别混用：

• docker compose start：只启动已存在的容器。如果之前是 down 删掉的，会报 no containers to start。
• docker compose restart：重启已有容器，不处理依赖顺序，也不会应用 compose 配置变更。
• docker compose up -d：最稳。容器在就启动，不在就按配置创建，还会检查依赖健康状态。

日常就用 up -d，它是幂等的。

8787 端口被占用#

1
lsof -iTCP:8787 -sTCP:LISTEN

docker compose up -d 报 bind: address already in use 就是它。要么杀掉占用的进程，要么改 compose 的映射（比如 "8080:8787"，注意只改宿主机那半边）。

postgres 一直 unhealthy#

1
docker compose logs postgres | tail -30

最常见的原因是：卷已经用旧密码初始化过了，但 .env 里的 POSTGRES_PASSWORD 改了。

PostgreSQL 镜像只在数据目录为空时才读 POSTGRES_PASSWORD 建用户，卷里已经有数据的话，这个环境变量会被忽略。结果是 artex 拿新密码去连，认证失败，启动就崩。

三条路，按代价从低到高：

• 把 .env 改回原密码（最快，数据不动）
• 进容器改数据库密码：docker compose exec postgres psql -U artex -c "ALTER USER artex PASSWORD '新密码';"，再同步改 .env
• docker compose down -v 推平重来（数据全丢）

忘记管理员密码#

不用重装，仓库里带脚本：

1
cd ~/tools/ARTEX
2
./reset-password.sh -m docker

它会在 postgres 容器里用 pgcrypto 生成 bcrypt 哈希，写回 settings 表的 auth.password_hash，和后端登录校验完全兼容。-m docker 表示走容器内 psql（compose 默认不对宿主机暴露 5432）。

页面能打开，但活动流一直转圈#

不是服务挂了，是 SSE 长连接被缓冲。如果前面套了 Nginx 反代，四个头必须加：

1
proxy_buffering off;
2
proxy_cache off;
3
proxy_read_timeout 3600s;
4
proxy_http_version 1.1;

本地直连 localhost:8787 不会有这个问题。

容器在，但日志一直重启#

1
docker compose logs -f artex

如果看到反复的启动失败，说明 start.sh 的守护逻辑在工作——它不是死循环，是在按退出码退避重拉。先解决根本错误，别急着 restart。

备份#

两份东西，缺一不可：

1
# 数据库
2
docker compose exec -T postgres pg_dump -U artex artex | gzip > artex-db-$(date +%F).sql.gz
3

4
# 现场文件（会比较大，实测 2.2G）
5
tar -czf artex-data-$(date +%F).tgz -C ~/tools/ARTEX data

./skills 是源码里的东西，跟着 git 走，不用单独备份。

更新#

1
cd ~/tools/ARTEX
2
docker compose pull artex
3
docker compose up -d artex
4
docker image prune -f

数据库迁移不用手动跑，ARTEX 每次启动会幂等重跑 schema.sql（ADD COLUMN / CREATE INDEX IF NOT EXISTS），重启即迁移。

想锁版本就在 .env 里写 ARTEX_TAG=v0.3.3，别一直用 latest——某天上游推了个不兼容的版本，只是重启一下就把自己搞崩了。