Dockyard

一套包含 600 多个 Portainer 应用模板（v3 格式），以及一个可浏览的静态网站（“Dockyard”），方便查找这些模板。

所有内容都由一个唯一可信来源生成：apps/ 中每个应用对应一个 YAML 文件，由一个小型 Python CLI 负责生成。该 CLI 会生成两项内容：

1. templates.json — 将其原始 URL 粘贴到 Portainer 的 设置 → 应用模板 → URL，即可一键部署目录中的所有应用。
2. docs/ — Dockyard 网站：展示包含徽标、说明、类别和链接的卡片，并支持搜索和筛选。

在 Portainer 中使用订阅源

1. 打开 Portainer，然后前往 设置 → 应用模板。
2. 将此 URL 粘贴到 URL 字段：

   https://cdn.jsdelivr.net/gh/bauerpawel/DOCKYARD@main/templates.json
   

3. 保存。
4. 在侧边栏中打开 应用模板（位于某个环境下）——现在只需单击即可部署下方的任意应用。

需要使用支持 v3 应用模板的 Portainer 版本。

有关 Open WebUI、Ollama、Backrest、Pocket ID、BentoPDF、Pangolin、Appwrite、搭配 RustFS 的 Plane，以及从 Hoarder 迁移到 Karakeep 的本地应用设置，请参阅本地应用设置。这些模板使用固定版本的镜像；启动堆栈前，请提供所需的密钥和部署设置。

订阅源通过 jsDelivr CDN 提供，而不是直接使用 raw.githubusercontent.com，从而在全球范围内实现更快、更可靠的加载。定期运行的工作流（见下文）会在每次重新构建后清除 jsDelivr 的缓存，因此 main 上的更改生效后，Portainer 几秒内就能获取最新的 templates.json。

网站

访问 https://dockyard.kim1.ovh 浏览同一目录——按名称搜索、按类别筛选，并点击任意应用的名称、徽标或说明以展开完整说明。每张卡片都链接到应用的 Docker Hub 页面，以及（如已知）其自身的源代码或主页。

界面提供英语、波兰语、德语和法语版本。网站会根据浏览器语言显示内容；页眉中的切换器可更改语言，?lang=pl（或 de、fr）可直接链接到相应语言版本。字符串存放在 site_src/i18n.json 中；应用说明保留英文。构建过程还会针对 site_src/CNAME 中指定的域名生成 robots.txt、sitemap.xml 和搜索引擎元数据（规范 URL、hreflang 替代项、Open Graph 卡片、JSON-LD）。

面向 AI Agent 的 MCP 服务

AI Agent 也可以通过 MCP 服务访问此目录：

https://dockyard.kim1.ovh/mcp

借助它，Claude、Codex、Grok、Gemini CLI、Cursor、VS Code 和其他 MCP 客户端可以搜索应用（list_apps）、读取应用详情（get_app）并准备部署计划（prepare_deploy）。该服务只会介绍应用并生成计划：它无法访问你的 Docker 或 Portainer；确认后，Agent 会在你的机器上执行部署。

使用以下命令将其添加到 Claude Code：

claude mcp add --scope user --transport http dockyard https://dockyard.kim1.ovh/mcp

对于其他客户端，请在浏览器中打开该地址。页面提供英语、波兰语、德语和法语的设置说明。

快速开始

需要 Python 3.14+。

最快捷的方式是从 apps/ 和 stacks/（重新）构建所有内容——如有需要会设置 .venv，构建 templates.json 和 docs/，并验证结果。此操作不会连接 Docker Hub（请参阅下文的保持元数据最新）：

run.bat                 # Windows
./run.sh                # Linux / macOS

额外参数会传递给 gallery build，例如：run.bat --repo-url https://github.com/bauerpawel/DOCKYARD。

默认 URL 来自 repository.json。Fork 应更新该文件或使用 --repo-url； 成功构建后，覆盖值会保存到该文件，以确保 feed、网站和 MCP 使用一致的仓库标识。 占位符 OWNER/REPO URL 会被拒绝。

如需手动逐步控制：

python -m venv .venv
.venv/Scripts/activate        # or: source .venv/bin/activate on Linux/macOS
pip install -e ".[dev]"

python -m gallery fetch-metadata   # refresh Docker Hub descriptions (cache/dockerhub.json)
python -m gallery build            # -> templates.json + docs/
python -m gallery validate         # check templates.json against Portainer's v3 schema
pytest                             # run the test suite

直接在浏览器中打开 docs/index.html，即可在本地预览网站。

托管元数据也来自 site_src/：编辑 site_src/CNAME 以使用自定义域名， 或删除它以使用默认 Pages 域名。可选的 site_src/.nojekyll 也会一并复制。 site_src/MCP_URL 保存网站在 feed URL 下宣传的 MCP 服务地址； 将其改为你自己的服务地址，或删除该文件以省略此说明。

发布前，构建会根据 schema/app_schema.json 验证应用 YAML，并根据 Portainer 架构验证生成的 feed。渲染和资源复制会在临时目录中进行。如果发布失败， 会恢复之前的 feed、网站和仓库配置；如果回滚失败，则会保留备份目录并报告其路径。

完整集成测试还需要 PHP 8.2+、Node.js 18+ 和 Docker Compose CLI。Compose 测试 只运行 config，无需 Docker 守护进程或正在运行的容器。

安全检查

使用 pip install -e ".[dev,audit]" 安装审计工具。在已激活的虚拟环境中：

python -m pip freeze --exclude-editable > .venv/audit-requirements.txt
python -m pip_audit -r .venv/audit-requirements.txt --no-deps --disable-pip --strict --progress-spinner off

快照包含已安装的传递依赖和开发依赖。CI 从 requirements/build.txt 和 requirements/dev.txt 安装 Python 包，这些文件中的依赖已锁定哈希，并为新版本设置了七天冷却期；更改 pyproject.toml 中的依赖后，请重新运行各文件头部的 uv pip compile 命令。该命令会保留现有锁定版本，因此如需提升锁定版本（例如清除审计发现），请添加 --upgrade（或 --upgrade-package <name>）。CI 会在推送、拉取请求和每周一运行测试、 构建／验证以及依赖审计。Dependabot 每周检查 Python 包、Composer 依赖和已固定版本的 GitHub Actions。审计范围和发现的问题请参阅 SECURITY_AUDIT.md。

MCP YAML 解析器及其许可证和 mcp/composer.lock 一并放在 mcp/vendor/ 中。 运行 composer audit --working-dir=mcp --locked --no-dev 检查 PHP 依赖。要更新依赖， 请运行 composer update --working-dir=mcp --no-dev，并将锁定文件与 mcp/vendor/ 一并提交。 Dependabot 的 Composer PR 只会修改锁定文件，因此合并前请在其分支上运行该命令： deploy/refresh.php 会拒绝发布 mcp/vendor/ 与锁定文件不匹配的版本，刷新测试也会失败。

MCP 计划在用户的计算机上运行，因此服务只会提供它能够验证的内容。来自其他仓库的 Stackfile 会按 stacks.lock.json 中固定的提交和 SHA-256 提供；上游更改只有经过审核并运行 python -m gallery pin-stacks --update 后才会进入计划。Compose 会根据允许列表进行检查：数据目录以外的主机路径、build、external 资源、未知键以及计划未设置的变量都需要 allow_privileged，而替换 PORTAINER_* 的堆栈则始终会被阻止。

stacks/ 下的本地堆栈需要非空密码，这些密码应通过 Portainer 中应用的环境字段或本地 .env 文件提供。对于 MCP 计划，请使用 local_secrets 并在本地替换 CHANGEME。重新部署时，保留现有卷正在使用的数据库密码；仅更改 .env 中的值不会轮换数据库凭据。n8n 使用 Web UI 中的所有者账户设置，不再使用已移除的 N8N_BASIC_AUTH_* 设置。

保持元数据最新

gallery fetch-metadata 是唯一会与 Docker Hub 通信的命令。它特意不包含在 run.bat／run.sh 的默认流程中，以免常规重建触发 Docker Hub 匿名速率限制；gallery build 始终读取 cache/dockerhub.json 中已有的缓存内容。

两个定时 GitHub Actions 工作流会自动处理这两种周期（参见 .github/workflows/）：

• build.yml - 在每次推送到 main 时运行（新添加的应用模板会立即上线；即使直接更改 templates.json 时没有经过 apps/／stacks/，也会清除其 jsDelivr 缓存），并在每周六运行一次作为保障。重建 templates.json + docs/，如有更改则提交，并清除 templates.json 和 stacks.lock.json 的 jsDelivr 缓存。也可以在 Actions 选项卡中按需运行。
• refresh-dockerhub.yml - 每月 1 日运行（这是最接近“每 30 天一次”的日历 cron 设置），刷新 cache/dockerhub.json、重新构建并提交。

两者均使用只读令牌以及 requirements/build.txt 中哈希固定的包进行构建。另有一个独立作业 （publish-generated.yml）不运行任何 Python 包，只提交生成的文件。main 要求通过 test (3.14) 和 audit 检查，因此该作业会先将提交推送到临时的 publish/* 分支，在该分支上运行 测试，将通过的作业记录为提交状态，然后才将 main 移至该提交。

需要临时刷新时，可随时在本地运行 python -m gallery fetch-metadata。

添加新应用

完整指南（字段参考、分类列表，以及如何查找可信的 logo/网站/图片）请参阅 CONTRIBUTING.md。简要步骤如下：

python -m gallery new my-app --type container   # or --type compose

这会创建 apps/my-app.yaml。填写以下字段：

name: My App
slug: my-app
category: Utilities
type: container                    # container | compose
image: namespace/my-app:latest     # required - must be a real Docker Hub image
compose: null                      # required for type=compose instead, e.g. stacks/my-app/docker-compose.yml
description: null                  # null = auto-fetch from Docker Hub; or write your own text
note: null                         # optional - Portainer deployment instructions; HTML supported
logo: https://.../my-app.png       # required
website: https://github.com/...    # optional - the app's own site or source repo
network: null                      # optional, container only - Docker network to attach to, e.g. host
command: null                      # optional, container only - override the container's command
privileged: null                   # optional, container only - true to run in privileged mode
restart_policy: null               # optional, container only - always | unless-stopped | on-failure | "no"
ports: ["8080/tcp"]
volumes: []
env: []

对于 type: compose，你可以：

• 将 stacks/my-app/docker-compose.yml 添加到此仓库，并通过 compose: stacks/my-app/docker-compose.yml 引用（请参阅现有的 stacks/* 文件夹——WordPress、Nextcloud、Gitea、Grafana+Prometheus、n8n 和 Ghost 都将主应用与其数据库配套配置），或
• 使用 repository: {url: https://github.com/..., stackfile: path/to/docker-compose.yml} 指向其他位置已有的 stackfile，而不是使用 compose:。

只有在 Compose 应用还需要查询 Docker Hub 元数据（即未手动设置 description）时，才需要 image；容器应用始终需要 image。

然后运行 python -m gallery fetch-metadata && python -m gallery build && python -m gallery validate 并提交结果（包括重新生成的 templates.json 和 docs/）——也可以直接推送；build.yml 工作流会替你重新构建（不过，在下次每月刷新之前，它不会为全新的镜像获取最新 Docker Hub 元数据，因此如果想让应用立即显示，请手动设置 description）。

每个应用至少需要 logo 和可解析的 description（手动设置或获取）；没有这些内容时，build 会拒绝生成条目。

报告错误和提出修复建议

发现模板损坏、website 或 logo 链接错误或过时、描述有误，或其他问题？请提交 issue——注明应用的 slug（即 apps/ 下的 YAML 文件名），以便轻松查找。

想自己修复？

1. Fork 此仓库并编辑相关文件——通常，单个应用对应 apps/<slug>.yaml，网站或工具对应 site_src//src/gallery/。
2. 运行 run.bat / ./run.sh 和 pytest，确认一切仍可正常构建、验证并通过测试。
3. 提交 pull request。

项目结构

apps/*.yaml                 # one file per app - the source of truth
stacks/<slug>/*.yml         # docker-compose files for type=compose apps
schema/templates_schema.json # vendored Portainer v3 JSON Schema, used by `validate`
src/gallery/                # the Python package (models, loader, Docker Hub client, builders, CLI)
site_src/                   # Jinja2 template, translations (i18n.json) + CSS/JS for the website
mcp/                        # PHP MCP server; guide/ holds the setup instructions it shows in a browser
docs/                       # generated website, served by GitHub Pages
cache/dockerhub.json        # cached Docker Hub metadata, refreshed by `fetch-metadata`
templates.json              # generated - the file Portainer actually fetches
tests/                      # pytest suite
requirements/               # hash-pinned CI dependencies, generated by `uv pip compile`
.github/workflows/          # scheduled rebuild + Docker Hub refresh (see above)

一次性部署设置

网站（docs/）由 GitHub Pages 直接从此仓库提供服务——无需单独托管。将此仓库推送到 https://github.com/bauerpawel/DOCKYARD 后：

1. 在仓库的 Settings → Pages 中，将源设置为分支 main、文件夹 /docs。之后，网站将位于 https://dockyard.kim1.ovh，并在 main 上的 docs/ 发生更改时自动更新——包括定时工作流推送的提交。
2. 就这些——上文的 Feed URL 和网站 URL 已指向此仓库。

要托管 Apache/MCP，请复制完整的 mcp/ 目录（包括 vendor/ 和 guide/）；请参阅 mcp/INSTRUKCJA.md。服务端从 jsDelivr CDN 读取 Feed 并缓存 15 分钟，因此同目录下的 templates.json 仅作为备用文件；repository.json 和 stacks/ 可让它使用本地 Compose 文件。在浏览器中打开服务端地址，会显示如何以英语、波兰语、德语或法语（mcp/guide/）将其添加到 Claude、Codex、Grok、Gemini CLI、Cursor 和 VS Code。可选的 deploy/refresh.php 更新器仅会在 GitHub Actions 中的 test 作业通过后安装提交，随后验证发布内容，并在替换前暂存所有构件。发布出错时会回滚之前的替换；Apache 配置和 MCP 缓存会保留。如果回滚本身失败，则会报告备份路径。

许可证

MIT——请参阅 LICENSE。

源自上游的 stack 配置保留其原始许可证： Appwrite 的 BSD-3-Clause 声明位于 stacks/appwrite/LICENSE.upstream，Plane 的 AGPL-3.0 许可证位于 stacks/plane/LICENSE.upstream。