tomyjan/itdog-agent repository overview

⁠ITDOG Agent Docker

将 ITDOG 贡献节点 Agent 封装为 Docker 镜像，支持 linux/amd64 和 linux/arm64。

• 源码仓库： GitHub⁠
• Docker 镜像： Docker Hub⁠

本仓库不是 ITDOG 官方项目。镜像中的 agent 二进制直接来自 ITDOG 官方下载地址：

• https://dl.itdog.cn/agent/agent_amd64.tar.gz
• https://dl.itdog.cn/agent/agent_arm64.tar.gz

⁠快速开始

⁠准备 UUID

先在 ITDOG 节点管理页面取得设备 UUID。启动节点时，唯一必填配置是 DEVICE_UUID。

Linux 或 macOS：

DEVICE_UUID='<your-uuid>' docker compose up -d

PowerShell：

$env:DEVICE_UUID = '<your-uuid>'
docker compose up -d

查看运行日志：

docker compose logs -f itdog-agent

停止节点：

docker compose down

docker compose down 会保留 agent 的节点状态。确认不再需要该节点的数据时，可以运行 docker compose down -v 一并删除数据卷。

⁠升级镜像

docker compose pull
docker compose up -d

镜像内 agent 二进制或 DEVICE_UUID 变化时，入口脚本会删除旧 node_id 并重新注册。普通容器重启会保留现有 node_id。

⁠使用其他镜像

Compose 默认拉取 tomyjan/itdog-agent:latest。fork 本仓库或使用固定版本时，可以额外设置 ITDOG_AGENT_IMAGE：

DEVICE_UUID='<your-uuid>' \
ITDOG_AGENT_IMAGE='yourname/itdog-agent:20260806' \
docker compose up -d

⁠容器运行配置

配置与官方裸机安装脚本保持以下对应关系：

官方 agent 是动态链接的 PyInstaller 单文件程序。运行镜像基于 Debian 12 slim，包含 glibc、zlib1g、CA 证书和 tini。下载阶段使用的 curl、tar 不会进入最终镜像。

⁠镜像发布

⁠Docker Hub 准备

1. 在 Docker Hub 创建名为 itdog-agent 的仓库。
2. 创建具有目标仓库 Read、Write、Delete 权限的 Personal Access Token。Docker Hub 更新仓库简介需要 Delete 权限对应的仓库管理能力。
3. 在 GitHub 仓库的 Settings > Secrets and variables > Actions 中添加：

发布目标由 Secret 动态计算为 <DOCKERHUB_USERNAME>/itdog-agent。Token 用于 Docker Hub 登录和更新仓库元信息，不会传入 Docker build 上下文或镜像层。

⁠手动发布

在 GitHub Actions 中运行 Docker 工作流。version 可以留空；留空时使用新加坡时区当天日期，格式为 YYYYMMDD，例如 20260806。

每次发布会同时推送：

• <DOCKERHUB_USERNAME>/itdog-agent:<version>
• <DOCKERHUB_USERNAME>/itdog-agent:latest

两个标签都是包含 linux/amd64、linux/arm64 的多架构 manifest。

镜像推送成功后，工作流还会把本 README 同步到 Docker Hub Overview，并更新仓库短描述。Dockerfile 中的 OCI 标签属于镜像元数据，Docker Hub 不会自动用它们填充仓库页面。

⁠由其他工作流调用

同一仓库内的工作流可以直接复用发布工作流：

jobs:
  publish:
    uses: ./.github/workflows/docker.yml
    with:
      version: '20260806'
    secrets: inherit

省略 version 时同样使用新加坡时区当天日期。

⁠自动检查更新

Check agent update 工作流每天新加坡时间 00:00 运行，也支持手动触发。它会：

1. 下载官方 amd64、arm64 agent。
2. 比较最近一次成功发布所缓存的二进制 SHA-256。
3. 任一架构变化时，调用 Docker 工作流发布镜像。
4. 发布成功后更新缓存；发布失败则保留旧缓存，便于下次重试。

更新检测比较解包后的实际 ELF 文件，不受 gzip 元数据变化影响。ITDOG 未提供签名或官方 SHA-256，因此下载真实性依赖官方 HTTPS 端点。

⁠本地构建

先下载并校验官方双架构二进制：

./scripts/download-agent.sh agent-downloads

构建当前平台镜像：

docker build --build-arg VERSION=dev -t itdog-agent:dev .

运行 Shell 测试：

bash tests/download-agent.test.sh
bash tests/docker-entrypoint.test.sh

⁠许可证

仓库代码按 LICENSE⁠ 提供。ITDOG Agent 二进制及服务的使用还应遵守 ITDOG 的相关条款。