diff --git a/setup.md b/setup.md
index 6e03c79..65d0cee 100644
--- a/setup.md
+++ b/setup.md
@@ -147,6 +147,14 @@ docker run -d --name gitea-runner --restart always \
 工作流把 vcpkg 二进制缓存放在容器内 `/opt/vcpkg-cache`，如需跨任务复用，可在
 job 容器配置中把该路径挂为持久卷。
 
+> **坑：注册地址必须是作业容器也能访问的地址。** 若 Gitea 与 act_runner 用
+> docker-compose 部署，千万不要用 `http://gitea:3000` 这类 compose 内部服务名
+> 注册（act_runner 容器自身可达，但 act_runner v3+ 的作业容器默认 host 网络，
+> 解析不了该名）。否则上传/下载 artifact 时报
+> `Failed to CreateArtifact: ... ENOTFOUND`。`GITEA_INSTANCE_URL` 用公网地址
+> （如 `https://gitea.example.com`）或宿主机映射地址（如 `http://10.0.0.10:39630`），
+> 改完编辑 `/data/config.yaml` 的 `runner.address` 重启即可，无需重新注册。
+
 **Windows（host 模式）**：在准备好构建环境的 Windows 机器上
 （Git、PowerShell、Visual Studio 2022、vcpkg 位于 `C:\vcpkg`，并预创建
 `D:\vcpkg-cache`；ImageMagick 等由工作流自动安装）：