企业官网建设流程全解析

从零到一：CapRover One Click Apps创建、测试并发布你的第一个一键应用完整教程

【免费下载链接】one-click-appsCommunity Maintained One Click Apps (https://github.com/caprover/caprover)项目地址: https://gitcode.com/gh_mirrors/on/one-click-apps

CapRover 一键应用（One Click Apps）是指通过一个 YAML 模板，就能在 CapRover 面板上"一键部署"到自建服务器上的应用。one-click-apps 是由社区维护的官方应用仓库，目前已收录354 个一键应用（从 Nextcloud、GitLab 到 Jellyfin、私有网盘一应俱全）。本教程将手把手带你完成整个流程：编写你的第一个一键应用 → 本地脚本校验 → 面板实测 → 构建发布，让其他 CapRover 用户也能一键安装它。

1️⃣ 认识仓库结构：354 个一键应用是怎么组织的

在动手之前，先花一分钟了解仓库的目录布局，这是编写第一个一键应用的基础：

💡 新手建议：先精读最简示例 privatebin.yml，它是官方推荐的入门模板；再看一个多服务示例 gitea.yml（一个应用同时拉起 Gitea + MySQL 两个容器）。

2️⃣ 手把手创建你的第一个一键应用（4 个步骤）

步骤 1：准备一份 Docker Compose 配置

CapRover 的一键应用本质是"带元数据的 Docker Compose 文件"。先为你要部署的应用找到（或自己写好）一份可用的 Compose 配置，这是第一步。

步骤 2：补齐 CapRover 专属模板

在 Compose 文件基础上做两处改造：

1. 在文件最顶部加上captainVersion: 4；
2. 在文件末尾追加caproverOneClickApp配置块，结构如下（对照 gitea.yml 理解更直观）：

captainVersion: 4 services: '$$cap_appname': image: myapp/image:$$cap_version environment: TZ: '$$cap_tz' caproverOneClickApp: variables: - id: '$$cap_version' label: App Version defaultValue: '1.2.3' validRegex: '/.{1,}/' instructions: start: 安装前展示给用户的说明 end: 部署成功后展示的总结 displayName: My Awesome App isOfficial: true description: 少于200字符的简介

步骤 3：定义变量，让用户自己填参数

变量以$$cap为前缀，可以出现在 YAML 任意位置，部署时会被用户在面板里填写的值替换。系统内置 3 个特殊变量，强烈建议用起来：

• $$cap_appname：应用名（同时作为服务名、域名前缀）
• $$cap_root_domain：根域名，两者组合即可得到myapp.rootdomain.com
• $$cap_gen_random_hex(length)：生成随机密码，适合做数据库默认口令

⚠️ 注意：字段默认不是必填的。只有设置了validRegex，用户才必须填写，否则该变量会被留空忽略。

步骤 4：添加同名应用图标

把应用图标（PNG 格式）放到 public/v4/logos/ 目录，文件名必须与 yml 文件名完全一致（例如myapp.yml对应myapp.png），校验脚本会强制检查这一点。

3️⃣ 本地自动校验：3 条命令把好质量关

仓库自带完整的检查工具链（见 package.json），提交前依次执行：

校验脚本会自动拦截以下常见问题：

• ❌captainVersion不是 4
• ❌ 缺少description/instructions.start/instructions.end
• ❌ 描述超过 200 个字符
• ❌logos/目录下找不到同名图标

4️⃣ 在 CapRover 面板中实测你的 One Click App

脚本通过只是第一步，真正的验收标准是能在面板里一键跑起来。测试路径非常短：

1. 登录你的 CapRover 管理面板；
2. 进入apps→ 点击One-Click Apps/Databases；
3. 在下拉列表最底部选择>> TEMPLATE <<；
4. 把你的 YAML 全文粘贴进文本框，点击NEXT；
5. 逐项填写变量值，确认应用按预期部署成功。

🧪 建议用一个全新的测试应用名跑一遍完整流程，重点检查：域名是否可访问、持久化数据卷是否挂载、多服务依赖顺序是否正确。

5️⃣ 构建并发布你的应用仓库

实测通过后，就要把成果"发布"出去，让别人的 CapRover 实例也能安装：

1. 执行npm run build，构建脚本（scripts/build_one_click_apps.js 与 scripts/build_one_click_apps_from_v4.js）会生成静态站点到./dist目录；
2. 把./dist用任意静态文件服务器托管，或通过 GitHub Pages 等静态托管发布（详见 README.md 中 "Building your own one-click app repository" 章节）；
3. 在目标 CapRover 面板的One-Click Apps/Databases页面底部，把你的仓库地址填入3rd party repositories输入框，点击Connect New Repository即可连接。

💡 还有一个进阶玩法：利用根目录的 captain-definition 文件，可以把你的私有应用仓库直接部署在自己的 CapRover 实例上——面板中选择"从 Git 仓库部署"并执行强制构建，仓库本身就成了一个 Web 服务（官方应用仓库即以此方式托管）。

6️⃣ 避坑指南：一键应用常见错误清单 🛠️

写在最后

回顾一下完整链路：编写 YAML 模板 → 补充同名图标 →npm run validate_apps校验 → 面板 TEMPLATE 实测 →npm run build发布仓库 → 面板连接第三方仓库。整个流程下来，你的第一个 CapRover 一键应用就正式上线了 🎉 仓库中 354 个现成模板就是最好的老师——挑一个你喜欢的应用照着改，是上手最快的方式。

【免费下载链接】one-click-appsCommunity Maintained One Click Apps (https://github.com/caprover/caprover)项目地址: https://gitcode.com/gh_mirrors/on/one-click-apps