Anubis 开发容器（Dev Container）完全指南：基于 Docker Compose 的 Go + Web 一体化贡献环境

Anubis 开发容器Dev Container完全指南基于 Docker Compose 的 Go Web 一体化贡献环境【免费下载链接】anubisWeighs the soul of incoming HTTP requests to stop AI crawlers项目地址: https://gitcode.com/gh_mirrors/anubis4/anubis本篇技术指南围绕 Anubis 项目一款用于拦截 AI 爬虫的 HTTP 反向代理与工作量证明验证服务官方提供的**开发容器Dev Container**展开讲解其 .devcontainer/README.md 及配套的 devcontainer.json、Dockerfile、docker-compose.yaml、poststart.sh 是如何共同构建一套即开即用的贡献者环境的。读完本文你将理解该镜像包含的全部工具链及其用途、容器内各服务Go 后端、Web 前端、Valkey 缓存、Playwright 测试如何协作并掌握在 VS Code 中一键打开、验证和运行 Anubis 开发环境的完整方法。为什么 Anubis 需要一个开发容器Anubis 是一个典型的全栈开源项目核心是 Go 编写的高性能代理与策略引擎同时包含大量前端与构建产物——templ模板见 lib/challenge 下的各.templ文件、TypeScript/WebAssembly 工作量证明客户端见 web 与 wasm、以及由 Docusaurus 驱动的文档站点见 docs。要贡献代码开发者往往需要同时准备 Go、Node.js、templ 代码生成器、WASM 交叉编译工具链等多套环境任何一环缺失都可能导致make build失败。开发容器的价值正在于此把整套工具链固化进一个可复现的镜像中任何贡献者打开仓库即可获得与维护者一致的开发环境。Anubis 官方在.devcontainer/README.md中明确说明该镜像基于 Xe/devcontainer-base/go底层是Debian Bookworm并在其上叠加了以下定制项Fish作为默认 shell附带定制主题Go最新稳定版Node.js最新稳定版Atuin用于在宿主机与开发容器之间同步 shell 历史Docker用于在容器内部管理、构建 Anubis 的容器镜像Ko用于构建生产级无基础镜像、纯静态的 Anubis 容器镜像Neovim配合 Git 使用。官方声明该容器已针对 Visual Studio Code 测试可用若在其他编辑器下遇到问题鼓励到仓库提交 issue 反馈见 CONTRIBUTING.md。开发容器的四件套文件构成与职责划分仓库 .devcontainer 目录下共四个文件各自承担不同的职责文件职责devcontainer.json开发容器的入口配置声明使用 Docker Compose、指定服务与工作目录、注入 VS Code 扩展与设置、定义前后置命令Dockerfile构建 workspace 基础镜像在xe/devcontainer-base/pre/go之上安装系统依赖并预置目录权限docker-compose.yaml定义多服务拓扑workspace 主工作区 Valkey 缓存 Playwright 测试服务poststart.sh容器启动后的依赖预拉取脚本加速首次构建从代码结构看这四者形成一条清晰链路devcontainer.json声明 → Docker Compose 编排 → Dockerfile 构建基础镜像 → 启动后执行 poststart 初始化。下面逐一深入。devcontainer.json容器入口配置逐项解读devcontainer.json 是开发容器的核心配置文件遵循 containers.dev 规范。逐项解读{ name: Dev, dockerComposeFile: [./docker-compose.yaml], service: workspace, workspaceFolder: /workspace/anubis, postStartCommand: bash ./.devcontainer/poststart.sh, features: { ghcr.io/xe/devcontainer-features/ko:1.1.0: {}, ghcr.io/devcontainers/features/github-cli:1: {} }, initializeCommand: mkdir -p ${localEnv:HOME}${localEnv:USERPROFILE}/.local/share/atuin, customizations: { vscode: { extensions: [esbenp.prettier-vscode, ms-azuretools.vscode-containers, golang.go, unifiedjs.vscode-mdx, a-h.templ, redhat.vscode-yaml, streetsidesoftware.code-spell-checker], settings: { chat.instructionsFilesLocations: { .github/copilot-instructions.md: true } } } } }关键点解读dockerComposeFileserviceworkspaceFolder容器环境并非独立拉起单个镜像而是复用 docker-compose.yaml 中定义的workspace服务并把工作目录挂载到容器内/workspace/anubis——这正是仓库在宿主机的路径挂载点。postStartCommand每次容器启动后都会执行 poststart.sh做依赖预下载详见下文。features通过 Dev Container Features 机制追加两个组件——xe/devcontainer-features/ko版本 1.1.0提供 Ko 构建工具devcontainers/features/github-cli提供 GitHub CLI便于在容器内直接操作 Git 远程与 CI。initializeCommand在宿主机上执行而非容器内为 Atuin 提前创建本地数据目录${localEnv:HOME}${localEnv:USERPROFILE}/.local/share/atuin保证 Atuin shell 历史同步在宿主机与容器间挂载打通。customizations.vscode自动安装 7 个与 Anubis 技术栈严格对应的 VS Code 扩展golang.goGo 语言支持对应核心后端a-h.templtempl 模板语法高亮对应 lib/challenge 下的.templ源文件unifiedjs.vscode-mdxMDX 文档支持对应 docs/blog 与 docs/docs 中的.mdx文件redhat.vscode-yamlYAML 配置校验对应 data 目录下的海量策略配置esbenp.prettier-vscode前端代码格式化ms-azuretools.vscode-containers容器管理辅助streetsidesoftware.code-spell-checker拼写检查与项目自身的 cspell 规范见 docs/developer/cspell.md呼应。Dockerfile基础镜像与系统依赖Dockerfile 以ghcr.io/xe/devcontainer-base/pre/go为基座只做最小化定制FROM ghcr.io/xe/devcontainer-base/pre/go WORKDIR /app COPY go.mod go.sum package.json package-lock.json ./ RUN apt-get update \ apt-get -y install zstd brotli redis \ mkdir -p /home/vscode/.local/share/fish \ chown -R vscode:vscode /home/vscode/.local/share/fish \ chown -R vscode:vscode /go CMD [/usr/bin/sleep, infinity]值得注意的设计细节提前 COPY 依赖清单go.mod、go.sum、package.json、package-lock.json被单独复制充分利用 Docker 层缓存——只要依赖清单没变后续镜像层就可以复用避免每次改动源码都重装依赖。apt-get install zstd brotli redis这三个系统包对应 Anubis 的运行时需求——zstd/brotli用于 gzip.go 等响应压缩/解压处理redis客户端则配合 Valkey 存储后端Redis 协议兼容使用见 lib/store/valkey/valkey.go。目录与权限修正为vscode用户预建 Fish 数据目录并 chown同时把/goGo 模块缓存目录的所有权交给vscode确保容器以非 root 用户运行时见 compose 中的user: vscode可以正常写缓存。CMD [/usr/bin/sleep, infinity]让容器作为长驻工作区存活等待 IDE 附着compose 中该 entrypoint 被注释掉实际由 devcontainer 框架管理生命周期。docker-compose.yamlworkspace Valkey Playwright 三服务拓扑docker-compose.yaml 是整套环境的编排核心定义了三个服务services: playwright: image: mcr.microsoft.com/playwright:v1.61.1-noble init: true network_mode: service:workspace command: - /bin/sh - -c - npx -y playwright1.61.1 run-server --port 9001 --host 0.0.0.0 valkey: image: valkey/valkey:8 pull_policy: always workspace: image: ghcr.io/techarohq/anubis/devcontainer build: context: .. dockerfile: .devcontainer/Dockerfile volumes: - ../:/workspace/anubis:cached environment: VALKEY_URL: redis://valkey:6379/0 user: vscode三个服务的角色与依据workspace主工作区。镜像来自ghcr.io/techarohq/anubis/devcontainer即上述 Dockerfile 构建产物将仓库根目录挂载到/workspace/anubiscached模式在 macOS 上优化文件同步性能并以vscode用户运行。valkey运行valkey/valkey:8作为会话/状态存储。Anubis 的存储层支持多后端见 lib/store 下的bbolt、memory、valkey、s3api等实现容器环境通过环境变量VALKEY_URL: redis://valkey:6379/0直接把 workspace 指向该服务对应 valkey 存储工厂 读取的地址配置。pull_policy: always保证始终拉取最新镜像。playwright运行微软官方mcr.microsoft.com/playwright:v1.61.1-noble镜像执行npx -y playwright1.61.1 run-server --port 9001 --host 0.0.0.0为 Anubis 的浏览器级集成测试提供远端驱动服务。network_mode: service:workspace让 playwright 与 workspace 共享网络命名空间测试即可通过localhost:9001访问它。这与 internal/test/playwright_test.go 中约定的测试参数完全对应——该测试通过-playwright默认ws://localhost:9001连接 Playwright Server并用真实浏览器验证各 User-Agent 应被 ALLOW / DENY / CHALLENGE 的策略行为如 Firefox 走工作量证明挑战、HeadlessChrome 与 Amazonbot/PerplexityBot 被直接拒绝、Kagi 按 IP 好坏区分放行或挑战。poststart.sh启动即预热的依赖加速脚本poststart.sh 内容非常短但作用关键#!/usr/bin/env bash pwd npm ci go mod download go install ./utils/cmd/... wait它在容器每次启动后并行执行三件事npm ci按package-lock.json精确安装前端依赖对应 web 与 docs 的 Node 生态go mod download预下载 Go 模块配合 Dockerfile 中 chown 过的/go缓存目录使后续go build/go test无需联网等待go install ./utils/cmd/...编译安装 utils 下的全部辅助命令行工具包括iplist2rule将 IP 列表转换为 Anubis 策略规则对应文档 docs/docs/admin/iplist2rule.mdxbackoff-retry带指数退避重试的命令包装器wazero-exec基于 Wazero 的 WASM 执行工具用于验证 wasm 目录下工作量证明模块的 Rust 实现。三条命令以并发执行、wait汇合最大限度缩短冷启动时间。这也是整个开发容器开箱即用体验的最后一环。容器内开发工作流从依赖到构建与测试进入容器后即可直接使用仓库 Makefile 定义的开发流程make deps等价于npm cigo mod download与 poststart.sh 预拉取一致make assets在deps基础上执行go generate ./...重新生成 templ 代码如 lib/challenge 下的*_templ.go再调用 wasm/scripts/build_wasm.sh 与 wasm/scripts/build_wasm2js.sh 编译工作量证明的 WASM 工件最后构建 web 与 xess 的前端资源make build产出./var/anubis主程序对应 cmd/anubis/main.go与./var/robots2policyrobots.txt 转策略工具对应 cmd/robots2policy/main.gomake test先构建资源再跑go test ./...make lintgo vetstaticcheck静态检查。其中构建、测试与运行 Anubis 服务时容器内通过VALKEY_URL环境变量自动接入 compose 中的 Valkey 实例若需要在本地跑 internal/test/playwright_test.go 的集成测试可直接复用localhost:9001的 Playwright Server测试支持-playwright-runner参数指定npx/docker/podman/none等启动方式。快速上手在 VS Code 中使用该开发容器官方测试场景是 Visual Studio Code推荐流程如下安装依赖确保宿主机已安装 Docker或兼容的容器运行时与 VS Code 的 Dev Containers 扩展ms-azuretools.vscode-containersdevcontainer.json 中也已为容器内 VS Code 预装。打开仓库在 VS Code 中打开仓库根目录选择在容器中重新打开Reopen in Container。等待构建与初始化VS Code 会依据 devcontainer.json 依次执行——宿主机侧运行initializeCommand创建 Atuin 目录 → 按 docker-compose.yaml 拉起 playwright、valkey、workspace 三服务 → 构建 workspace 镜像 → 容器启动后执行poststart.sh预拉取依赖。验证环境进入容器终端后可用fish --version、go version、node --version确认工具链版本用redis-cli -h valkey ping验证 Valkey 连通随后直接执行make build构建 Anubis 二进制。开发与测试编辑 Go / templ / TypeScript 源码后使用预装的扩展获得语法高亮与格式化支持运行make test跑单元测试或按 internal/test/playwright_test.go 的说明执行浏览器集成测试。相关文件与延伸阅读容器配置devcontainer.json、Dockerfile、docker-compose.yaml、poststart.sh本地开发指南docs/developer/local-dev.md、docs/developer/building-anubis.md、docs/developer/smoke-tests.mdx存储后端lib/store/valkey/valkey.go、lib/store/interface.go集成测试internal/test/playwright_test.go构建工作流Makefile、wasm/scripts/build_wasm.sh策略与工具utils/cmd/iplist2rule/main.go、docs/docs/admin/iplist2rule.mdx总而言之Anubis 的开发容器不是简单的一个镜像而是一套配置驱动 多服务编排 启动预热的完整贡献者体验方案Dockerfile 提供可复现的工具链底座Compose 把 Valkey 与 Playwright 这两个测试依赖做成零配置的内置服务poststart 脚本消除首次构建的等待焦虑。对于希望为本项目贡献代码的开发者而言这是官方推荐的、成本最低的入场方式。【免费下载链接】anubisWeighs the soul of incoming HTTP requests to stop AI crawlers项目地址: https://gitcode.com/gh_mirrors/anubis4/anubis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考