DROP

DROP

部署、运行、运维、发布

一款轻量级、可自托管的平台即服务（PaaS），专为“放入文件夹即可部署”工作流而打造。无需配置，即可部署 Node.js、Python、Go、静态站点和容器化应用。

放入一个文件夹，即可获得一个 URL。80% 的使用场景无需配置。

功能

• 零配置部署 — 自动检测应用类型、构建并启动
• 多运行时 — 支持 Node.js、Python、Go、Docker、静态站点和 SPA，并能检测 Next.js、Nuxt、SvelteKit、Astro、Express、FastAPI、Flask 等框架
• 主机名路由和自动 HTTPS — Let's Encrypt 证书、每个应用可使用自定义域名
• PostgreSQL 自动配置 — 应用拥有独立数据库，并注入 DATABASE_URL
• 托管 Redis — 在 drop.yaml 中选择启用
• 热重载 — 编辑文件后，应用会重新构建并重启
• 单体仓库 — 在一个仓库中运行多个服务，共用主机名并通过同源 /api 路由
• MCP 服务 — 可从 Claude、Claude Code、Cursor 和其他 Agent 部署和管理应用
• Docker 隔离 — 在容器中运行租户应用并限制资源，适用于多用户设置
• REST API 和 Web 控制面板 — 提供完整 API，支持 JWT 和 API 密钥身份验证，并配有实时监控界面
• 持久化数据 — 应用数据通过 DROP_DATA_DIR 在升级后继续保留
• 跨平台 — 支持 Windows、Linux 和 macOS

文档

完整文档位于 dropkit.sh/docs，所有 CLI 命令和 API 端点均收录在 参考文档 中。本 README 介绍 DROP 的安装、公开部署前应阅读的信任模型，以及灾难恢复。

主题	位置
drop.yaml 字段、单体仓库、必需的密钥	文档 → drop.yaml
环境变量（平台变量和注入变量）	文档 → 环境变量
持久化数据目录	文档 → 持久化数据
支持的运行时及检测方式	文档 → 运行时与检测
Caddy 路由、HTTPS、DNS-01 证书、自定义域名	文档 → 路由与 HTTPS
数据库自动配置及其触发条件	文档 → 数据库
日志捕获和保留	文档 → 日志
连接 Claude、Cursor 和其他 Agent	文档 → 集成
所有 CLI 命令和 REST 端点	参考文档

本仓库还包含：HTTPS 设置、Git 重新部署和自定义域名、Agent 部署。

Agent 可使用 deploy-to-drop 技能（Claude Code、Cursor 和任何兼容 SKILL.md 的 Agent）自行部署到 DROP。

系统要求

发行版安装（推荐，Linux）： 全新的 Debian/Ubuntu 主机，并拥有 root 访问权限。install.sh 会为你安装 Node.js、PostgreSQL、Caddy，以及（如果选择 --isolation=docker）Docker Engine — 无需自行安装工具链。

从源代码构建： Node.js 20+、npm 9+，以及用于主机名路由的可选组件 Caddy 2.0+。

安装

install.sh 拒绝直接通过 curl 管道运行——它需要在磁盘上有一份自身副本才能正常工作——因此请先保存，再运行：

curl -fsSL https://github.com/JulesNsenda/drop/releases/latest/download/install.sh -o install.sh && sudo bash install.sh --from-release --isolation=docker

--from-release 会安装最新发布的版本：无需 git clone，也无需在你的机器上构建 TypeScript 或 Vite。（仍需要 Node.js，安装程序会为你安装。npm 可能会记录 cpu-features 的可选构建失败——这不会造成影响；它是 ssh2 的可选原生加速组件，不安装也能完成安装。）

首次安装时，你必须明确选择一种隔离模式：

• --isolation=docker（推荐）——租户应用在 Docker 容器中构建和运行，并受到资源限制，无法访问平台机密。
• --isolation=none——租户应用以系统用户 drop 的身份运行，该用户同时拥有平台的加密密钥和 JWT/OAuth 机密。只有在所有部署者都完全可信的单机上才选择此模式；请参阅安全与信任模型。

DNS 指向此服务器后，添加 --domain=example.com --https [email protected]；也可以使用 --from-release=v1.0.0 固定特定版本，而不是安装最新版本。

服务启动后，从平台日志中获取一次性管理员密码，并立即修改：

journalctl -u drop-platform -b --no-pager | grep -A1 'Default Admin Credentials'

Windows：install.sh 面向使用 systemd/apt 的 Linux 服务器。在 Windows 上，请运行 install.bat（或从源代码构建），然后直接使用 drop serve 启动——Windows 在 isolation: none 模式下受到全面支持。

验证即将以 root 身份运行的内容

install.sh 会在安装任何内容之前自行验证下载的 tarball 的 SHA-256 校验和。若要进一步验证构建是否由此仓库自己的 GitHub Actions 完成，请检查构建来源证明：

gh release download --repo JulesNsenda/drop -p drop-dist.tar.gz
gh attestation verify drop-dist.tar.gz --repo JulesNsenda/drop

每次发布时，发布工作流都会为本仓库公开后构建的版本附加证明。如果 gh attestation verify 报告某个版本没有证明，说明该版本发布于启用证明之前——请改用已发布的 drop-dist.tar.gz.sha256，install.sh 会自动检查该文件。

每个版本还会附带 drop-dist.tar.gz（已编译的服务器、CLI 和仪表板）、其 .sha256 文件以及 install.sh，因此你可以在隔离网络的服务器上手动下载并检查它们。所有版本都列在这里。

从源代码构建

适用于贡献者，或希望从分支而非发布版本运行的情况：

git clone https://github.com/JulesNsenda/drop.git
cd drop
npm install
(cd src/dashboard && npm install)   # the dashboard is a separate package
npm run build                       # compiles the server AND builds the dashboard
npm link                            # makes the 'drop' command available globally

如果你只修改了后端代码，npm run build:server 可以跳过仪表板构建。

首次启动时，drop serve 会在控制台打印一次性管理员密码。请立即修改。

快速开始

drop serve                               # start the platform
cp -r my-app /var/drop/data/webapps/     # drop a folder in (Windows: xcopy to C:\drop\data\webapps\)

DROP 会检测应用类型、安装依赖、执行构建；如果应用需要 PostgreSQL 数据库，则会配置该数据库；随后在分配的端口上启动应用。之后，你可以通过 http://localhost:<port> 访问应用；安装 Caddy 后，也可以通过 http://my-app.localhost 访问。编辑任何文件后，应用都会重新构建并重启。

仪表板位于 http://localhost:3000/dashboard，提供应用列表、逐个应用的启动/停止/重启、机密、自定义域名、部署历史、日志、用户管理以及 Claude 连接器详情。

有关 CLI 和 REST API，请参阅参考文档。运行中的 DROP 会将 /dashboard/docs 和 /dashboard/reference 重定向到该页面。

安全与信任模型

在让任何你并非完全信任的人访问 DROP 之前，请先阅读本文。

DROP 提供两种明确的隔离模式，各自具有不同的信任保障。

isolation: none（默认）— 单用户 / 可信部署

部署应用意味着以 DROP 进程用户的身份在主机上运行其代码（安装 / 构建脚本和应用进程）。已部署的应用或其构建脚本可以读取其他应用的数据以及平台自身的文件。

适用于： 这是你的机器或由你控制的机器，并且所有拥有部署权限的人都值得信任。请将部署权限视同 Shell 访问权限。

• 在此模式下，切勿启用 allowSignup — DROP 会在启动时拒绝运行。
• 仅在可信的本地机器上禁用身份验证（DROP_DISABLE_AUTH=true）。
• 此模式完全支持 Windows。

isolation: docker — 多用户 / 邀请用户

应用在 Docker 容器中构建和运行，并受到严格的资源限制（--cap-drop=ALL、--security-opt no-new-privileges、内存 / CPU 限制、--pids-limit）。构建容器无法访问平台机密，也无法连接 LAN 或云元数据端点。

如实说明的残余风险（已记录，并未隐瞒）：

• 共享内核：容器不是 VM。内核漏洞会授予完整的主机访问权限。此处已记录此风险，但未采取缓解措施。
• 出站流量：容器可以访问互联网（安装软件包需要联网）。容器到 LAN / 元数据端点的连接会被阻止；完整的出站流量策略将在未来版本推出。
• 共享域名 Cookie：同一可注册域名的子域名共享同站点上下文。位于 a.yourdomain.com 和 b.yourdomain.com 的应用可以读取彼此的 Cookie。多租户使用时，请使用专用的 baseDomain，或将其提交到 Public Suffix List。
• 开放注册（allowSignup: true）会启用自助注册。针对恶意行为的工具、下架操作手册，以及针对恶意公开访问的出站流量管控，都是未来要完成的工作。在此之前，请将开放互联网注册视为已记录的残余风险。
• 依赖项必须安装到应用目录中。 构建和运行在不同的临时容器中进行，这些容器仅共享 /app 绑定挂载（不提交镜像），因此只有写入应用目录的依赖项才能进入运行环境。Node（node_modules）、Go（编译后的二进制文件）和 Python（位于 /app 中的 .venv，其 bin/ 会加入运行时 PATH）的依赖项都会安装到该目录中。自定义构建命令安装到系统 site-packages 或全局前缀中的任何内容，都会随构建容器一起丢弃 — 构建会“成功”，但应用随后会在启动时导入失败。

需要在 Linux 上安装 Docker Engine（在 Windows / macOS 上使用 Docker Desktop 仅适用于开发 / 尽力支持此模式）。

构建容器以平台自身的非 root 用户身份运行，因此无需 CAP_DAC_OVERRIDE 即可写入应用源代码。通过 DROP 部署的应用（git 部署、webhook、drop deploy）会自动归该用户所有。如果你改为手动将文件夹放入 data/webapps/，请将其所有者设为平台用户（例如 chown -R drop:drop）— 如果文件夹由其他用户所有（例如使用 root 执行 sudo cp），构建将因 EACCES 而失败（这是默认的故障关闭设计；DROP 不会为了绕过此问题而以 root 身份运行不可信构建）。

两种模式下均已加固的方面

• API 身份验证（JWT + API 密钥）、角色层级（readonly/user/admin）
• 基于套接字对端地址的速率限制（无法通过伪造 x-forwarded-for 绕过）
• 所有文件 I/O 和部署路径上的路径遍历与路径包含检查
• webhook 和 git 克隆 URL 的 SSRF 防护（私有地址范围 + DNS 解析检查）
• 严格的 drop.yaml 架构（拒绝未知键；TLS 路径限制在应用目录内）
• drop.yaml 值绝不会直接传入 docker run 参数或挂载配置
• 携带 .git 元数据的上传归档会被直接拒绝
• Git 凭据通过环境传递给 git，从不写入 .git/config 或显示在 ps 中
• 对所有部署 / 构建 / 启动 / 机密 / 挂起操作进行审计日志记录
• 内置 PostgreSQL 强制使用 scram-sha-256；Unix 套接字仅允许对端身份验证

所有与安全相关的设置请参阅 .env.example。

备份与恢复

DROP 将关键状态保存在 data/drop-svc/ 下的文件存储中（凭据、加密密钥、加密密钥文件、Webhook、应用状态），以及 PostgreSQL 中——包括内部的 drop_internal 数据库和每个已配置的应用数据库。使用以下命令对所有内容创建快照：

drop backup            # writes data/backup/backup-<timestamp>/
drop backup --keep 14  # keep the newest 14, prune the rest

备份包含 JSON/YAML 存储、encryption.key、drop_internal 的 pg_dump，以及 databases/ 下每个应用数据库的 pg_dump -Fc（另有一个生成的 databases/restore-roles.sql，用于重新创建应用数据库角色）。请自行安排备份（cron / Task Scheduler）——DROP 不会自动运行备份。如果任何转储失败——无论是应用数据库、内部数据库，还是数据库枚举本身——备份命令都会以非零状态码退出，因此只检查退出码的 cron 任务仍能发现部分备份。

注意：备份仅适用于相同平台。 在 Windows 上创建的备份无法在 Linux 上恢复（反之亦然）——随附的 PostgreSQL 二进制文件和数据布局因平台而异。

恢复

drop restore 可还原备份。此操作具有破坏性——会覆盖当前文件存储和数据库——因此平台运行时拒绝执行，必须提供 --confirm，并会先显示执行计划：

drop restore data/backup/backup-<timestamp>/            # prints the plan, writes nothing
drop restore data/backup/backup-<timestamp>/ --confirm  # actually restores

• 请先停止平台。 正在运行的 drop serve 会将状态保存在内存中，并可能覆盖恢复结果；如果检测到守护进程或仍在 API 端口响应的前台平台，drop restore 都会拒绝执行。

• 文件存储（data/drop-svc/、data/appconf/webapps/）会复制回原处，并保留其权限模式（密钥仍为 0600）。

• 数据库会通过随附的 psql/pg_restore 还原——但请注意，drop server stop 也会停止随附的 PostgreSQL，因此在正常流程中，drop restore 会发现其无法访问，打印每个数据库的确切命令，并跳过自动数据库还原步骤。若要自动还原数据库，请先以独立模式启动 PostgreSQL，然后重新运行：

  "<dropRoot>/apps/drop-svc/pgsql/bin/pg_ctl" -D "<dropRoot>/data/db" start
  drop restore data/backup/backup-<timestamp>/ --confirm
  

数据库步骤会使用当前正在运行的服务器的 data/drop-svc/.pg-superuser 进行身份验证（在覆盖任何文件之前读取），而不是使用备份中的副本。恢复后，在平台下次重启之前，正在运行的服务器密码可能与已恢复的文件不一致。

手动操作（等效于 drop restore 执行的操作，也是跳过数据库还原步骤时打印的内容）：

BIN=<dropRoot>/apps/drop-svc/pgsql/bin ; export PGPASSWORD="$(cat data/drop-svc/.pg-superuser)"
# 1. Recreate app roles (clean server runs clean; on a re-run, "role already exists" is expected/benign)
"$BIN/psql" -h 127.0.0.1 -p 5433 -U postgres -d postgres -f databases/restore-roles.sql
# 2. Recreate + restore each database, drop_internal included (--create makes the DB AND restores REVOKE CONNECT)
"$BIN/pg_restore" -h 127.0.0.1 -p 5433 -U postgres --create -d postgres databases/drop_<app>.dump
#    (re-run over existing DBs: add --clean --if-exists ; check exit codes, don't ignore stderr)

请使用 apps/drop-svc/pgsql/bin 下随附的 pg_restore/psql，不要使用系统的 Postgres 客户端，因为主版本不匹配可能会损坏还原结果。备份仅适用于相同平台（Windows 备份无法在 Linux 上恢复），且数据库还原往返流程未纳入自动化测试——请先在非生产环境中验证。

删除前的数据库转储

删除应用（drop remove <app> / DELETE /api/v1/apps/:name）时，会先转储其已配置的数据库，再将其删除：在删除数据库之前，DROP 会将其转储到 data/backup/pre-delete/<db>-<timestamp>.dump，并生成配套的 <db>-<timestamp>.restore-role.sql（用于重新创建角色，因为 -Fc 不会捕获角色）。只有在转储验证通过后才会删除数据库；如果 pg_dump 失败或 Postgres 未运行，数据库会保持不变，以免丢失。删除前转储会保留 DROP_PREDELETE_RETENTION_DAYS 天（默认 3 天），并在之后每次删除时自动清理——请在此之前将需要永久保留的转储复制到本机以外的位置。

运行 drop remove --keep-data <app> 可完全跳过先转储再删除的流程，并保留数据库。

若要还原删除前转储，请按上述恢复部分中的相同步骤操作：使用 psql 执行其 .restore-role.sql，然后对 .dump 文件运行 pg_restore --create。

升级

DROP 可在平台重启期间保持由 PM2 管理的应用进程运行，但平台重启时会停止并重新启动捆绑的 PostgreSQL 和 Caddy，因此升级期间数据库连接和路由可能会短暂中断。

• 请先备份（drop backup）。
• 如果你运行着守护进程，升级后请运行 drop server stop，然后运行 drop serve -d——单独执行 pm2 restart 会保留 PM2 转储中的旧参数和路径。
• **注意：**从 v1.0 起，drop serve -d 会采用此前被忽略的 --root/--domain/--https/... 标志。如果你一直传入未生效的标志，现在它们将生效——升级前请检查这些标志（例如，多余的 --https 将实际启用 HTTPS，并验证你的域名配置）。

各版本的重大变更列于 CHANGELOG 中对应版本说明的开头。

开发

npm run dev          # start in development mode
npm run build        # build server + dashboard
npm test             # run tests
npm run lint         # lint

分支模型和约定：docs/GIT-BRANCHING-MODEL.md。路线图详情：docs/VERSION-ROADMAP.md。

路线图

• 零配置部署、热重载、PostgreSQL 自动配置、REST API + Web 仪表板、Caddy 反向代理、自动 HTTPS (0.1.0–0.3.0)
• Docker 隔离、托管 MCP 服务 + OAuth 2.1、单体仓库/多服务部署、托管 Redis、自定义域名 (1.0.0)
• 日志聚合与搜索
• 多节点集群

许可证

MIT 许可证——详情请参阅 LICENSE。