FOCUS BOARD
把今天真正重要的事做完
添加任务，开始 25 分钟专注，并在当前浏览器中保存进度。
TASKS
今日任务
0 个未完成
还没有任务，先添加一件今天最重要的事。
FOCUS TIMER
25 分钟专注
一次只处理一件事。
25:00
准备开始
SignatureDoesNotMatch`
`说明：本页面包含联盟链接。通过这些链接购买产品时， 我们可能获得佣金，但不会因此增加你的购买价格。
查看产品详情 ``` 其中： - `sponsored` 表示这是商业或联盟性质的链接； - `nofollow` 可避免向商业链接传递常规搜索权重； - `noopener` 用于降低新窗口访问原页面对象的风险。 是否使用 `target="_blank"` 应根据实际体验决定。移动端用户通常更适合直接在当前页面打开，不必为了保留落地页而强制新窗口。 ## 部署 Cloudflare Pages 的两种方式 ### 方式一：连接 Git 仓库 如果页面会持续修改，推荐使用 GitHub 或 GitLab 仓库。 基本步骤如下： 1. 将静态网站上传到 Git 仓库； 2. 登录 Cloudflare 控制台； 3.进入 Workers & Pages； 3. 创建 Pages 项目并连接 Git 仓库； 4. 选择对应分支； 5. 设置构建命令和输出目录； 6. 部署项目。 纯静态项目如果不需要构建工具，可以不填写构建命令，输出目录填写实际存放网页的目录，例如 `public`。 如果使用 Astro、Hugo、Vite 等工具，则应根据该工具设置构建命令。例如 Vite 项目常见的输出目录是 `dist`，但不能机械照抄，必须以项目配置为准。 Git 部署的优势是每次提交代码后可以自动构建，也可以通过预览部署检查修改结果。 ### 方式二：直接上传或使用 Wrangler 不想使用 Git 时，可以直接上传静态文件，也可以通过 Wrangler 命令行部署： ```bash npx wrangler pages deploy public ``` 首次执行时，命令行会要求登录并选择或创建项目。 直接上传适合一次性页面，但如果后续需要频繁更新、回滚或多人协作，Git 工作流更容易管理。创建项目之前最好确定部署方式，因为不同项目类型之间的迁移并不总是无缝完成。 ## 绑定域名时不要绕过 Cloudflare 配置 Cloudflare 会为 Pages 项目生成一个 `pages.dev` 子域名，可以直接访问。但用于联盟营销时，独立域名通常更适合品牌建设，也便于更换托管平台。 在 Pages 项目的自定义域名设置中添加域名后，根据提示完成 DNS 配置即可。不要只在 DNS 页面随意添加一条记录，却不在 Pages 项目中绑定域名，否则可能出现证书、域名验证或路由问题。 建议同时确定主域名版本，例如： ```text https://example.com ``` 然后把其他版本统一重定向到主域名： ```text https://www.example.com → https://example.com ``` 页面中还应设置规范网址： ```html ``` 如果为不同广告渠道复制大量内容几乎相同的页面，应谨慎处理索引和规范网址，避免形成重复内容。 ## 如何查看静态落地页访问数据 ### 使用 Cloudflare Web Analytics Cloudflare Web Analytics 适合查看静态落地页的基础访问情况。它与服务器日志不同，主要通过浏览器端脚本收集页面访问和性能数据。 常见指标包括： - 页面浏览量； - 访客和访问次数； - 热门页面； - 引荐来源； - 国家或地区； - 浏览器和设备信息； - Core Web Vitals 等页面性能指标。 配置时可以在 Cloudflare 控制台进入 Web Analytics，添加站点后复制系统生成的脚本。不要照抄其他网站的令牌，必须使用自己站点对应的代码。 生成的代码通常放在页面 `` 之前： ```html文章正文
", "excerpt": "文章摘要", "status": "draft" } ``` ### 1\. 使用 Application Password 如果 WordPress 版本和站点配置支持 Application Password，可以为专用编辑账号创建应用密码，并通过 HTTPS 使用 HTTP Basic Authentication。 安全要点： - 单独创建自动化账号，不使用管理员账号； - 只授予创建和编辑文章所需的最低权限； - 凭据保存在 n8n Credentials 中； - 不把账号密码写进 Code 节点或请求正文； - 不在执行日志和通知消息中输出凭据； - 人员离职或工作流停用后立即撤销应用密码。 创建文章后，WordPress 会返回文章 ID。可以将 ID 写回选题表，并发送审核链接： ```text https://www.example.com/wp-admin/post.php?post=文章ID&action=edit ``` ### 2\. 默认使用 `draft` 最推荐的流程是： 1. n8n 创建草稿； 2. 编辑在 WordPress 后台核查； 3. 编辑修改分类、标签、图片和链接； 4. 编辑使用 WordPress 自带的立即发布或定时发布功能。 这样不需要再开发一个容易被滥用的“批准发布”接口。 ### 3\. 必须自动发布时增加批准状态 如果业务确实需要自动定时发布，应满足以下条件： - 数据库中的 `status` 已被授权编辑改为 `approved`； - 文章正文的哈希值与批准时一致； - 发布前再次检查外链和必填字段； - 发布账号权限受到限制； - 每次发布写入审计记录； - 失败时进入人工处理队列，而不是无限重试。 只有满足条件，n8n 才能将 WordPress 状态设置为 `publish`，或按 WordPress REST API 支持的日期字段创建计划文章。服务器、WordPress 与 n8n 的时区必须保持一致，避免定时偏差。 ## 六、发布后还应该自动化什么 内容发布并不代表工作结束。对于以赚钱为目的的网站，发布后的维护往往比增加文章数量更重要。 ### 1\. 失效链接巡检 每周读取已发布文章中的外链，检查： - DNS 或连接失败； - HTTP 404、410； - 重定向链过长； - 联盟目标页失效； - 原始资料被删除。 不要对第三方网站高频并发请求。设置合理间隔、超时和重试次数，遇到 429 时遵守服务端返回的限制信息。 ### 2\. 陈旧内容提醒 可以按以下条件建立更新队列： - 文章超过指定周期未复核； - 文中包含旧版本号或过期年份； - 主要来源已经更新； - 产品下架或接口变更； - 搜索流量明显下降； - 转化页面跳出或失效。 系统只负责提醒，不能仅通过替换年份把旧文章伪装成新内容。 ### 3\. 收益和转化回收 如果广告平台、联盟平台或分析工具提供官方接口，可以按其权限和条款获取数据，并关联到文章 ID。建议重点观察： - 每篇文章的有效访问； - 搜索点击和展示； - 联盟链接点击； - 线索提交； - 单篇内容维护成本； - 每千次有效访问产生的收入； - 更新后流量和转化是否改善。 不要在 n8n 中存放不必要的访客个人信息。需要处理表单线索时，应设置保留期限、访问权限和删除机制。 ## 七、在 VPS 上安全部署 n8n 以下方案使用 Docker Compose、PostgreSQL 和 Caddy。Caddy 负责申请及续期 HTTPS 证书，n8n 和数据库不直接暴露到公网。 截至 2026 年 8 月，n8n 仍在持续更新。生产环境不要从不明教程复制过时版本号，也不要长期无审核地跟随浮动镜像。应从 n8n 官方文档或官方镜像仓库确认当前稳定版本，完成测试后固定镜像标签或摘要。 ### 1\. 服务器前置条件 VPS 至少需要： - 一个指向服务器公网 IP 的域名； - 受支持并及时更新的 Linux 发行版； - Docker Engine 与 Docker Compose 插件； - 开放 80 和 443 端口； - SSH 密钥登录； - 可用的异地备份位置。 目录结构： ```text /opt/n8n/ ├── compose.yaml ├── .env └── Caddyfile ``` ### 2\. 创建环境变量文件 `/opt/n8n/.env` 示例： ```dotenv N8N_DOMAIN=n8n.example.com GENERIC_TIMEZONE=Asia/Shanghai POSTGRES_DB=n8n POSTGRES_USER=n8n POSTGRES_PASSWORD=替换为高强度随机密码 N8N_ENCRYPTION_KEY=替换为独立的长随机字符串 N8N_IMAGE=docker.n8n.io/n8nio/n8n:替换为已测试的稳定版本 ``` 可以使用系统密码生成工具生成随机值，例如： ```bash openssl rand -base64 48 ``` 限制文件权限： ```bash cd /opt/n8n chmod 600 .env ``` `N8N_ENCRYPTION_KEY` 用于保护 n8n 中保存的凭据。丢失该密钥后，即使数据库仍在，原有凭据也可能无法正常解密，因此必须单独备份。 ### 3\. Docker Compose 配置 `compose.yaml`： ```yaml services: postgres: image: postgres:16-alpine restart: unless-stopped environment: POSTGRES_DB: ${POSTGRES_DB} POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: - CMD-SHELL - pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB" interval: 10s timeout: 5s retries: 10 networks: - internal n8n: image: ${N8N_IMAGE} restart: unless-stopped environment: DB_TYPE: postgresdb DB_POSTGRESDB_HOST: postgres DB_POSTGRESDB_PORT: 5432 DB_POSTGRESDB_DATABASE: ${POSTGRES_DB} DB_POSTGRESDB_USER: ${POSTGRES_USER} DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD} N8N_HOST: ${N8N_DOMAIN} N8N_PORT: 5678 N8N_PROTOCOL: https N8N_EDITOR_BASE_URL: https://${N8N_DOMAIN}/ WEBHOOK_URL: https://${N8N_DOMAIN}/ N8N_PROXY_HOPS: 1 N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY} GENERIC_TIMEZONE: ${GENERIC_TIMEZONE} TZ: ${GENERIC_TIMEZONE} EXECUTIONS_DATA_PRUNE: "true" N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true" volumes: - n8n_data:/home/node/.n8n depends_on: postgres: condition: service_healthy networks: - internal - proxy caddy: image: caddy:2-alpine restart: unless-stopped environment: N8N_DOMAIN: ${N8N_DOMAIN} ports: - "80:80" - "443:443" - "443:443/udp" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config depends_on: - n8n networks: - proxy networks: internal: internal: true proxy: volumes: postgres_data: n8n_data: caddy_data: caddy_config: ``` 这个配置没有把 n8n 的 5678 端口映射到宿主机，也没有暴露 PostgreSQL 的 5432 端口。公网只能通过 Caddy 访问 HTTPS 服务。 `Caddyfile`： ```caddy {$N8N_DOMAIN} { encode zstd gzip reverse_proxy n8n:5678 } ``` 启动： ```bash cd /opt/n8n docker compose config docker compose pull docker compose up -d docker compose ps docker compose logs --tail=100 n8n ``` 确认域名解析正确后，访问： ```text https://n8n.example.com ``` 首次使用时按照页面提示创建所有者账号。使用长且唯一的密码；如果当前部署版本支持多因素认证，应为高权限账号启用。 ### 4\. 防火墙与 SSH 如果服务器使用 UFW，可以按实际 SSH 端口调整规则： ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 443/udp sudo ufw enable sudo ufw status ``` 修改 SSH 配置前必须确认密钥登录成功，并保留一个已登录会话，避免把自己锁在服务器外。通常应做到： - 禁止 root 远程密码登录； - 禁止普通账号密码登录，只使用密钥； - 及时安装安全更新； - 不对公网开放 Docker API、PostgreSQL 和 n8n 5678 端口； - 云服务商安全组与系统防火墙采用相同的最小开放策略。 ## 八、n8n 凭据、Webhook 与节点安全 ### 1\. 不在节点中明文保存密钥 API 密钥、WordPress 应用密码和数据库密码应保存在 n8n 的 Credentials 中。避免以下做法： - 写入 Code 节点； - 放进工作流名称； - 发送到聊天通知； - 记录在 Git 仓库； - 直接粘贴到错误日志； - 导出工作流后未经检查公开分享。 即使凭据字段在界面中被隐藏，也要限制谁能查看、编辑和运行相关工作流。 ### 2\. Webhook 必须验证请求 Webhook URL 不应仅依赖“地址难以猜到”。根据上游能力选择： - HTTP Basic Auth； - Header Token； - HMAC 签名； - 时间戳加随机数，防止重放； - 来源 IP 限制； - 请求体大小限制； - 固定字段和 JSON Schema 校验。 不同服务的签名算法不同，必须以该服务的官方文档为准，不能自行假设签名格式。 Webhook 收到请求后，应先验证身份，再进行数据库写入或发布操作。对于支付、审批和发布等高风险操作，还要记录事件 ID，并以唯一约束避免重复执行。 ### 3\. 谨慎安装社区节点 社区节点本质上可以执行代码并接触工作流数据。安装前应检查： - 来源与维护者； - 更新记录； - 依赖包； - 所需权限； - 是否会发送遥测或外部请求； - 是否有官方节点可以替代。 不需要社区节点时，不要为了省几个配置步骤随意安装。高风险工作流可以部署在独立实例中，与普通内容任务隔离。 ### 4\. 控制执行记录中的敏感数据 内容采集可能把完整网页、用户表单、令牌或个人信息保存在执行记录中。应根据实际业务： - 开启执行数据清理； - 减少成功任务的详细保存； - 对个人信息做脱敏； - 设置合理保留时间； - 不把大型正文长期保存在执行日志中； - 定期检查磁盘占用。 具体配置项可能随 n8n 版本变化，部署时应对照当前官方文档，而不是直接照搬旧环境变量。 ## 九、备份、恢复与升级 只备份数据库还不够。至少需要保存： 1. PostgreSQL 数据； 2. n8n 数据卷； 3. `N8N_ENCRYPTION_KEY`； 4. Compose 与 Caddy 配置； 5. 工作流导出文件； 6. WordPress 及其媒体文件； 7. 恢复步骤和账号信息。 数据库备份示例： ```bash cd /opt/n8n mkdir -p backups docker compose exec -T postgres \ sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' \ | gzip > "backups/n8n-$(date +%F-%H%M).sql.gz" ``` 备份文件应加密并复制到另一台服务器或对象存储中。仅把备份留在同一块 VPS 磁盘上，无法防范磁盘损坏、误删除或账号失陷。 升级流程建议为： 1. 阅读 n8n 官方发布说明和迁移说明； 2. 备份数据库、数据卷和加密密钥； 3. 在测试环境运行目标版本； 4. 更新 `.env` 中固定的镜像版本； 5. 执行 `docker compose pull`； 6. 执行 `docker compose up -d`； 7. 检查日志、凭据、Webhook 和关键工作流； 8. 确认备份能够恢复。 不要在无人值守的生产环境中每天自动拉取最新镜像。自动更新虽然省事，但数据库迁移、节点行为变化或依赖不兼容可能直接中断发布流程。 ## 十、什么时候需要队列模式 个人站或小型内容团队通常可以先使用单实例。以下情况才需要考虑 n8n 的队列模式、Redis 和多个 worker： - 大量任务同时运行； - 网页处理或文件转换持续时间长； - Webhook 高峰明显； - 单个任务会阻塞其他发布任务； - 需要独立扩展执行节点。 队列模式会增加 Redis、worker、并发控制、监控和备份复杂度。不能仅通过增加 worker 无限提高采集速度，还必须遵守第三方接口限额，并避免重复执行和数据库竞争。 在扩展前，先处理以下问题往往更有效： - 减少无意义轮询； - 使用增量游标； - 对重复数据提前终止； - 限制并发； - 缩短执行日志保留时间； - 将大文件放入合适的对象存储； - 把耗时任务和发布任务分开。 ## 十一、n8n 自托管替代方案怎么选 n8n 并不是所有项目的唯一选择。 | 方案 | 更适合的情况 | 需要注意 | | ----------------- | ------------------------- | ------------------------ | | n8n | API、数据库、CMS 和通知系统之间的可视化编排 | 自托管仍需要运维；商业分发或托管场景要核对许可证 | | Activepieces | 希望使用可视化自动化并评估开源、自托管路线 | 先确认所需连接器和部署能力 | | Node-RED | 事件流、设备、消息队列和轻量接口编排 | 内容运营模板和 SaaS 连接体验可能不同 | | Windmill | 团队以脚本、内部工具和工程化任务为主 | 更偏开发者工作流 | | Huginn | 以监测、事件代理和信息聚合为主 | 界面和维护方式与 n8n 不同 | | 自写脚本＋Cron | 工作流简单、稳定，团队能维护代码 | 审计、重试、凭据管理和可视化需要自己实现 | | Make、Zapier 等托管服务 | 不想维护 VPS，希望快速接入现成 SaaS | 数据位置、执行限制和长期成本需自行评估 | 需要特别注意，n8n 的源码可用不等于可以不受限制地把它包装成对外收费的自动化托管服务。用于自己的内部业务，与向客户提供 n8n 本身作为托管产品，不是同一种使用方式。涉及白标、嵌入、转售或商业托管时，应阅读当时有效的官方许可证和商业条款。 ## 十二、最小可行版本：先跑通这三条工作流 如果是第一次搭建，不要一开始就做全自动内容工厂。可以先完成以下最小版本。 ### 工作流 A：选题入库 ```text 每天执行 → 读取 3～5 个可靠 RSS 或官方接口 → 标准化字段 → PostgreSQL 去重 → 按主题关键词评分 → 将高分选题发送给编辑 ``` ### 工作流 B：创建审核草稿 ```text 读取编辑批准的选题 → 整理官方资料 → 生成提纲或初稿 → 检查来源、链接和必填项 → WordPress 创建 draft → 通知编辑并记录文章 ID ``` ### 工作流 C：发布后维护 ```text 每周读取已发布文章 → 检查外链和更新时间 → 标记需要更新的文章 → 创建编辑任务 → 汇总流量与转化数据 ``` 先观察一个完整运营周期，再决定是否增加模型调用、并发 worker、自动排期或更多数据源。 ## 十三、常见失败方式 ### 1\. 把“发布量”当成收入指标 文章数量不会自动转化为搜索流量或收入。更有意义的是有效访问、读者停留、订阅、咨询和购买。 ### 2\. 批量改写其他网站 这种方式缺乏新增价值，还可能涉及版权、接口条款和搜索平台的规模化内容滥用政策。AI 参与本身并不必然构成问题，问题在于内容是否为了操纵排名而批量生产、是否准确、是否对读者有实际帮助。 ### 3\. 给自动化账号管理员权限 WordPress 管理员凭据一旦泄露，影响范围远高于一个只能创建草稿的编辑账号。 ### 4\. Webhook 无验证 公开 Webhook 如果能触发发布、删除或高成本模型调用，可能被扫描器和攻击者滥用。 ### 5\. 只部署，不备份 VPS、数据库和 Docker 数据卷都可能损坏。没有异地备份和恢复演练，就不能算完成部署。 ### 6\. 工作流失败后无限重试 无限重试可能重复发布文章、重复发送消息，甚至反复调用付费接口。应限制重试次数，并使用事件 ID、文章 ID或数据库唯一键保证幂等。 ## 结语 n8n 内容网站自动化真正有价值的地方，不是用机器代替编辑，而是把分散、重复、容易遗漏的运营动作变成一条可观察、可审计、可恢复的流水线。 对于希望通过内容网站获得长期收入的运营者，较合理的顺序是： 1. 先验证细分主题和变现路径； 2. 建立合法、稳定的数据来源； 3. 用数据库维护选题与审核状态； 4. 让 n8n 自动采集、去重和通知； 5. 默认把内容写入 WordPress 草稿； 6. 保留人工事实核查与最终发布； 7. 对 VPS、凭据、Webhook 和备份进行安全加固； 8. 根据真实流量与转化数据逐步扩展。 一套每天发布五篇但经过验证、能够持续更新的工作流，通常比每天无人审核地生成几十篇文章更有商业价值，也更容易长期维护。 ### 自建 n8n Webhook 无回调？从 Docker、反向代理到 HTTPS 环境变量的完整排查 URL: https://isoziyuan.com/p/100103/ Last updated: 2026-08-27T11:43:04.000Z 不少自建 n8n 实例会出现这样的情况：编辑器可以正常打开，工作流也能手动运行，但第三方平台发送事件后，Webhook 节点始终没有收到数据；或者 n8n 显示的回调地址仍然是 `localhost:5678`、HTTP 地址或错误域名。 这类问题通常不是 Webhook 节点本身失效，而是请求链路中的某一层配置不一致： ```text 第三方平台 ↓ HTTPS 请求 域名 / CDN / 防火墙 ↓ Nginx、Caddy 或 Traefik ↓ Docker 内部 HTTP n8n:5678 ↓ 对应的工作流与 Webhook 节点 ``` 下面按照“先定位请求到了哪里，再修复外部 URL”的思路进行排查。 ## 一、先确认使用的是测试 URL 还是生产 URL n8n 的 Webhook 节点通常会显示两类地址： ```text 测试地址： https://n8n.example.com/webhook-test/... 生产地址： https://n8n.example.com/webhook/... ``` 二者用途不同。 ### 测试 URL `/webhook-test/` 只适合在编辑器中调试。通常需要先打开 Webhook 节点，点击类似“Listen for test event”或“Execute workflow”的按钮，让 n8n 进入等待状态，然后再发送请求。 如果直接把测试 URL 填到第三方平台，并期待它长期接收回调，通常会出现： - 编辑器没有处于监听状态； - 等待状态已经结束； - 第一次测试成功，后续请求却收不到； - 重启 n8n 后测试地址不再处于监听状态。 ### 生产 URL 正式接收回调应使用 `/webhook/` 地址，并确保对应工作流已经激活或发布。不同 n8n 版本的界面措辞可能略有不同，以当前界面中的“Active”“Activate”或“Publish”为准。 因此，第一步应检查： 1. 第三方平台填写的是 `/webhook/`，不是 `/webhook-test/`； 2. 工作流已经激活或发布； 3. Webhook 节点没有被删除、替换或更改路径； 4. 请求方法与节点设置一致，例如都是 `POST`； 5. 修改工作流后，生产版本是否已经重新发布。 如果第三方平台此前注册的是旧 URL，修改域名或路径后，还需要在对方平台更新回调地址。对于自动注册 Webhook 的触发器节点，通常还需要停用后重新激活工作流，以便重新注册订阅。 --- ## 二、用 curl 判断问题发生在哪一层 不要一开始就反复修改 Docker Compose。先从外部网络请求生产 URL，观察 HTTP 状态码。 ```bash curl -i -X POST \ 'https://n8n.example.com/webhook/your-path' \ -H 'Content-Type: application/json' \ -d '{"source":"curl","test":true}' ``` 最好从不在服务器内网的设备执行，例如本地电脑或另一台云主机。这样才能真实经过公网 DNS、HTTPS 和反向代理。 ### 常见结果的含义 | 现象 | 通常说明 | | ------------------------------------ | --------------------------- | | DNS 无法解析 | 域名记录错误或尚未生效 | | 连接超时 | 安全组、防火墙、端口映射或代理未监听 | | TLS 证书错误 | 证书过期、域名不匹配或证书链不完整 | | 301、302、307、308 | 存在 HTTP 跳转、路径跳转或登录重定向 | | 401、403 | Webhook 鉴权、代理认证、WAF 或访问规则拦截 | | 404 | 路径错误、工作流未激活，或代理改写了路径 | | 413 | 请求体超过反向代理限制 | | 502、504 | 代理无法连接 n8n，或上游超时 | | n8n 返回 “webhook not registered” 一类信息 | URL 存在，但当前没有对应的生产 Webhook | | 请求成功但工作流无记录 | 需要检查执行模式、队列、节点逻辑和执行日志 | 还可以分别测试首页和 Webhook： ```bash curl -I https://n8n.example.com/ curl -i -X POST https://n8n.example.com/webhook/your-path ``` 编辑器首页能打开，不代表 `/webhook/` 一定被正确转发。有些代理规则只处理了根路径，或者将 Webhook 路径转发到了其他服务。 --- ## 三、确认 Docker 中的 n8n 是否真的正常监听 先查看容器状态： ```bash docker compose ps ``` 然后查看实时日志： ```bash docker compose logs -f n8n ``` 如果不是使用 Compose： ```bash docker ps docker logs -f n8n ``` 重点关注以下问题： - 容器是否反复重启； - 端口是否为默认的 `5678`； - 数据目录是否有权限错误； - 数据库是否连接失败； - 是否存在重复的 Webhook 路径； - 工作流激活时是否注册失败； - 代理请求到达时，日志中是否有对应记录。 ### 在 Docker 网络内部测试 n8n 如果 Nginx 也运行在 Docker 中，可以从代理容器测试： ```bash docker exec -it nginx sh ``` 进入后，根据容器内可用工具执行： ```bash wget -S -O- http://n8n:5678/ ``` 或者： ```bash curl -I http://n8n:5678/ ``` 这里的 `n8n` 应当是 Compose 服务名，并且代理与 n8n 必须加入同一个 Docker 网络。 如果代理运行在宿主机，而 n8n 映射到了本机回环地址，可以测试： ```bash curl -I http://127.0.0.1:5678/ ``` 判断原则很简单： - Docker 内部访问失败：先修复容器、网络或监听问题； - Docker 内部成功，公网失败：重点检查反向代理、HTTPS、防火墙和 DNS； - 公网请求能到达 n8n，但提示 Webhook 不存在：重点检查 URL、请求方法和工作流状态。 --- ## 四、正确理解 `WEBHOOK_URL` 的作用 反向代理场景中，n8n 容器内部通常使用 HTTP： ```text http://n8n:5678 ``` 但外部访问地址是： ```text https://n8n.example.com ``` n8n 仅根据容器内部监听信息，未必能正确推断外部协议和域名。因此需要显式设置： ```yaml WEBHOOK_URL: https://n8n.example.com/ ``` `WEBHOOK_URL` 的作用是告诉 n8n：外部系统应通过这个基础地址访问 Webhook。 它主要影响： - Webhook 节点显示的生产 URL； - 部分触发器节点向第三方平台注册的回调地址； - n8n 对外生成的 Webhook 基础地址。 但要注意： > `WEBHOOK_URL` 不会自动配置 DNS、申请证书、开放防火墙，也不会替代反向代理。 如果域名没有指向服务器，或者 Nginx 没有转发请求，仅设置这个变量仍然无法收到回调。 建议 URL 使用完整 HTTPS 地址，并保留末尾斜杠： ```yaml WEBHOOK_URL: https://n8n.example.com/ ``` 不建议填写： ```yaml WEBHOOK_URL: http://localhost:5678/ WEBHOOK_URL: http://n8n:5678/ WEBHOOK_URL: https://192.168.1.10/ ``` 除非这些地址确实能够被发送回调的第三方平台访问。 --- ## 五、推荐的 Docker Compose 配置 以下示例采用“宿主机或独立代理负责 HTTPS，n8n 容器内部使用 HTTP”的部署方式。 ```yaml services: n8n: image: docker.n8n.io/n8nio/n8n:latest restart: unless-stopped environment: N8N_HOST: n8n.example.com N8N_PORT: 5678 N8N_PROTOCOL: https WEBHOOK_URL: https://n8n.example.com/ N8N_EDITOR_BASE_URL: https://n8n.example.com/ N8N_PROXY_HOPS: 1 GENERIC_TIMEZONE: Asia/Shanghai TZ: Asia/Shanghai N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY} N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true" volumes: - n8n_data:/home/node/.n8n ports: - "127.0.0.1:5678:5678" volumes: n8n_data: ``` 将示例中的 `n8n.example.com` 替换为实际域名。 ### 这些变量分别解决什么问题 #### `N8N_HOST` 指定 n8n 对外使用的主机名： ```yaml N8N_HOST: n8n.example.com ``` 不要在这里填写 `https://`，也不要添加路径。 #### `N8N_PROTOCOL` 外部用户通过 HTTPS 访问时设置为： ```yaml N8N_PROTOCOL: https ``` 这不代表 n8n 容器自身必须监听 HTTPS。常见做法仍然是由反向代理终止 TLS，容器内部使用 HTTP。 #### `WEBHOOK_URL` 明确指定外部 Webhook 基础地址： ```yaml WEBHOOK_URL: https://n8n.example.com/ ``` 这是“n8n 显示 localhost Webhook”或“第三方注册到了 HTTP 地址”时最关键的变量。 #### `N8N_EDITOR_BASE_URL` 用于明确编辑器的外部访问地址： ```yaml N8N_EDITOR_BASE_URL: https://n8n.example.com/ ``` 它与 `WEBHOOK_URL` 的职责不同：前者偏向编辑器访问地址，后者偏向 Webhook 回调地址。在同一域名部署时，两者通常保持一致。 #### `N8N_PROXY_HOPS` n8n 位于反向代理后方时，需要正确处理受信代理传入的转发头： ```yaml N8N_PROXY_HOPS: 1 ``` 这里不是永远固定为 `1`，而是取决于真实代理层数。例如： ```text 客户端 → Nginx → n8n ``` 通常是一层。 如果链路是： ```text 客户端 → CDN/负载均衡 → Nginx → n8n ``` 则需要结合实际架构和 n8n 当前版本文档确定代理跳数。不要为了“快速修好”盲目设置过大的值，否则可能错误信任客户端伪造的转发头。 ### 不建议把 5678 直接暴露到公网 如果反向代理运行在宿主机，可以绑定到本机回环地址： ```yaml ports: - "127.0.0.1:5678:5678" ``` 如果反向代理也运行在同一个 Docker 网络中，甚至可以不声明 `ports`，只使用： ```yaml expose: - "5678" ``` 然后由代理通过服务名访问： ```text http://n8n:5678 ``` 这比直接使用下面的配置更安全： ```yaml ports: - "5678:5678" ``` 后者可能让 n8n 绕过 HTTPS 和反向代理直接暴露在公网，具体还取决于宿主机防火墙规则。 --- ## 六、Nginx 反向代理参考配置 如果 Nginx 运行在宿主机，而 n8n 映射到 `127.0.0.1:5678`，可以使用类似配置： ```nginx server { listen 80; listen [::]:80; server_name n8n.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; listen [::]:443 ssl; http2 on; server_name n8n.example.com; ssl_certificate /etc/letsencrypt/live/n8n.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem; client_max_body_size 16m; location / { proxy_pass http://127.0.0.1:5678; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 300s; proxy_send_timeout 300s; } } ``` 修改配置后先检查语法： ```bash sudo nginx -t ``` 确认无误后重新加载： ```bash sudo systemctl reload nginx ``` ### 必须保留的转发信息 至少应正确传递： ```nginx proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; ``` 其中 `X-Forwarded-Proto` 尤其重要。外部请求明明是 HTTPS，但 n8n 容器收到的是来自 Nginx 的 HTTP；如果代理没有告诉 n8n 原始协议是 HTTPS，就可能生成错误的 HTTP 地址或产生安全 Cookie、重定向方面的问题。 ### 不要意外删除 Webhook 路径 下面两种 `proxy_pass` 写法在涉及路径拼接时可能产生不同结果： ```nginx proxy_pass http://127.0.0.1:5678; ``` ```nginx proxy_pass http://127.0.0.1:5678/; ``` 当 `location` 使用子路径时，末尾斜杠会影响路径替换规则。最稳妥的方案是给 n8n 使用独立子域名： ```text https://n8n.example.com/ ``` 而不是部署到： ```text https://example.com/n8n/ ``` 如果必须部署在子路径下，还需要同步检查 n8n 路径配置、编辑器资源路径、Webhook URL 和代理改写规则，不能只修改 Nginx 的 `location`。 --- ## 七、修改环境变量后必须重建容器 修改 `.env` 或 `compose.yaml` 后，仅重启容器有时不会应用新的容器环境配置。建议执行： ```bash docker compose up -d --force-recreate ``` 然后确认容器实际获得的环境变量： ```bash docker compose exec n8n env | grep -E \ 'N8N_HOST|N8N_PORT|N8N_PROTOCOL|WEBHOOK_URL|N8N_EDITOR_BASE_URL|N8N_PROXY_HOPS' ``` 预期能看到类似结果： ```text N8N_HOST=n8n.example.com N8N_PORT=5678 N8N_PROTOCOL=https WEBHOOK_URL=https://n8n.example.com/ N8N_EDITOR_BASE_URL=https://n8n.example.com/ N8N_PROXY_HOPS=1 ``` 如果输出仍然是旧值，检查： - 是否修改了错误的 Compose 文件； - 是否使用了多个 `-f` 配置文件； - `.env` 是否位于正确目录； - 变量是否被宿主机环境覆盖； - 是否存在旧容器； - YAML 缩进是否正确。 可以查看 Compose 展开后的最终配置： ```bash docker compose config ``` 注意该命令可能输出解析后的敏感变量，不要将完整结果公开发布。 --- ## 八、HTTPS 正常打开，不代表回调一定能通过 第三方平台通常对 Webhook HTTPS 有更严格的要求。浏览器能访问，不代表平台一定接受。 需要检查以下项目。 ### 1\. 证书域名是否匹配 证书必须覆盖实际回调域名，例如： ```text n8n.example.com ``` 不能使用只覆盖 `example.com`、但不包含该子域名的证书。 查看证书信息： ```bash openssl s_client \ -connect n8n.example.com:443 \ -servername n8n.example.com /dev/null \ | openssl x509 -noout -subject -issuer -dates ``` ### 2\. 证书链是否完整 服务器一般应提供完整证书链。Nginx 使用 Let’s Encrypt 时，通常应配置 `fullchain.pem`，而不是只配置单张站点证书。 ### 3\. 回调是否发生了重定向 第三方平台未必会跟随重定向，尤其是签名校验严格的平台。直接把 HTTPS 最终地址注册为回调 URL，不要依赖： ```text HTTP → HTTPS 旧域名 → 新域名 无斜杠 → 有斜杠 登录页 → Webhook ``` 检查是否重定向： ```bash curl -I https://n8n.example.com/webhook/your-path ``` 对于只允许 `POST` 的 Webhook，应使用实际请求方法测试，而不是仅依赖 `HEAD`： ```bash curl -i -X POST \ https://n8n.example.com/webhook/your-path \ -H 'Content-Type: application/json' \ -d '{}' ``` ### 4\. 防火墙是否开放 443 检查云平台安全组、宿主机防火墙以及前置负载均衡规则。一般只需向公网开放： - TCP 80：证书签发或跳转，可根据部署方式决定； - TCP 443：正式 HTTPS 访问。 没有必要把 n8n 的 `5678` 端口直接开放给公网。 --- ## 九、代理和 WAF 容易忽略的拦截点 如果前面还有 CDN、Web 应用防火墙或零信任访问网关，需要额外检查。 ### 登录保护拦截了 Webhook 如果在整个 n8n 域名前增加了统一登录认证，第三方平台请求 Webhook 时可能被重定向到登录页或直接收到 `401`。 表现通常是： ```text 第三方平台 → /webhook/... → 登录页 ``` Webhook 机器请求无法像用户一样完成交互式登录。需要在安全策略中为必要的 Webhook 路径设置合适的机器访问规则，同时通过以下方式保护接口： - Webhook 节点自带的鉴权方式； - 随机且不可猜测的路径； - 请求头令牌； - 第三方平台提供的签名校验； - 来源 IP 限制，但仅在对方提供稳定出口地址时使用。 不要仅依赖“URL 没公开”作为唯一安全措施。 ### WAF 将 JSON 或表单误判为攻击 如果 n8n 日志中完全没有请求，但 CDN 或 WAF 日志中出现 `403`，需要检查托管规则、速率限制和请求体检测策略。 不要直接关闭所有安全规则。应针对确定的回调路径、来源和请求特征设置最小范围的例外。 ### 请求体过大 Nginx 默认请求体限制可能无法满足包含文件、长文本或大 JSON 的回调。日志中常见： ```text client intended to send too large body ``` 可以按实际需求调整： ```nginx client_max_body_size 16m; ``` 不要无上限放大。对于大文件，更合理的方式通常是让第三方只发送文件 URL，再由 n8n 按权限下载。 ### 上游响应超时 某些第三方平台要求 Webhook 很快返回成功状态。如果工作流收到请求后执行耗时操作，平台可能认为回调失败并重复发送。 可考虑让 Webhook 尽快返回，再继续执行后续逻辑。具体响应模式应在 Webhook 节点中根据业务需求设置，并配合幂等机制防止重复处理。 --- ## 十、看到请求但工作流没按预期执行 当代理日志和 n8n 日志都能看到请求时，问题已经不再是“公网无法到达”，而应检查工作流本身。 ### 请求方法不一致 Webhook 节点配置为： ```text POST ``` 第三方平台却发送： ```text GET ``` 即使路径完全相同，也不会匹配正确的 Webhook。 使用详细模式确认请求： ```bash curl -v -X POST https://n8n.example.com/webhook/your-path ``` ### 路径大小写或斜杠不一致 检查以下差异： ```text /webhook/order-created /webhook/Order-Created /webhook/order-created/ /webhook/order_created ``` 不要假设代理、n8n 或第三方平台会自动将它们视为同一路径。 ### 同一路径存在冲突 多个工作流使用相同请求方法和生产 Webhook 路径，可能导致注册冲突或激活失败。检查 n8n 日志，并为每个入口使用唯一、清晰的路径。 ### Webhook 鉴权不匹配 如果节点启用了 Basic Auth、Header Auth 或其他认证，curl 测试和第三方平台也必须发送对应凭据。 例如使用请求头： ```bash curl -i -X POST \ 'https://n8n.example.com/webhook/your-path' \ -H 'Content-Type: application/json' \ -H 'X-Webhook-Token: replace-with-real-token' \ -d '{"test":true}' ``` 不要把密钥直接硬编码在公开的工作流截图、Compose 文件或代码仓库中。 ### 回调签名验证失败 很多平台会发送时间戳、签名和原始请求体。签名验证应严格按照对方官方文档处理，尤其注意： - 是否使用原始请求体； - JSON 是否被重新序列化； - 字符编码是否一致； - 时间戳是否超过允许范围； - 密钥是否来自正确环境； - 请求头名称是否区分大小写或被代理过滤。 如果签名失败，应明确返回鉴权失败，而不是为了让流程“先跑起来”长期关闭签名验证。 --- ## 十一、通过代理访问日志确定请求是否到达 为 Nginx 查看实时访问日志： ```bash sudo tail -f /var/log/nginx/access.log ``` 同时查看错误日志： ```bash sudo tail -f /var/log/nginx/error.log ``` 然后让第三方平台重新发送回调，或使用 curl 请求。 可以根据日志快速分层判断： ### 访问日志中没有请求 可能原因： - 第三方平台根本没有发送； - 域名解析到错误服务器； - CDN、负载均衡或防火墙提前拦截； - 使用了旧回调 URL； - 请求走了 IPv6，但服务器 IPv6 配置不正确。 检查 DNS： ```bash dig +short A n8n.example.com dig +short AAAA n8n.example.com ``` 如果存在 `AAAA` 记录，但服务器没有正确提供 IPv6 服务，部分平台可能优先尝试 IPv6 并失败。此时应修复 IPv6 链路或删除不正确的 `AAAA` 记录。 ### Nginx 有请求，n8n 没有日志 可能原因： - `proxy_pass` 指向错误地址； - Nginx 匹配了其他 `location`； - 路径被改写； - 请求被 Nginx 直接返回； - 上游连接失败。 ### n8n 有请求，但没有成功执行 可能原因： - 工作流未激活或未发布； - Webhook 路径、方法不匹配； - 节点认证失败； - 工作流执行报错； - 执行数据保留策略导致界面中看不到预期记录。 --- ## 十二、一套高效的排查顺序 遇到 n8n Webhook 收不到回调时，可以按下面顺序执行，避免同时修改多个变量。 ### 第一步：核对 URL 确认第三方平台使用： ```text https://实际域名/webhook/实际路径 ``` 而不是： ```text http://localhost:5678/... http://容器名:5678/... https://实际域名/webhook-test/... ``` ### 第二步：确认工作流状态 - 使用生产 URL； - 工作流已激活或发布； - 请求方法正确； - 节点路径没有变化； - 自动注册型触发器已重新激活。 ### 第三步：从公网 curl ```bash curl -i -X POST \ https://n8n.example.com/webhook/your-path \ -H 'Content-Type: application/json' \ -d '{"test":true}' ``` 记录状态码、响应头和响应体。 ### 第四步：检查三层日志 依次查看： 1. CDN、负载均衡或 WAF 日志； 2. Nginx 访问日志与错误日志； 3. n8n 容器日志。 请求在哪一层消失，问题就优先在哪一层处理。 ### 第五步：验证内部连通性 ```bash curl -I http://127.0.0.1:5678/ ``` 或者在 Docker 网络中： ```bash curl -I http://n8n:5678/ ``` ### 第六步：检查关键环境变量 至少核对： ```text N8N_HOST N8N_PROTOCOL WEBHOOK_URL N8N_EDITOR_BASE_URL N8N_PROXY_HOPS ``` ### 第七步：重建容器 ```bash docker compose up -d --force-recreate ``` 然后再次查看 n8n 界面中显示的生产 Webhook URL。 ### 第八步：重新注册外部回调 - 在第三方平台保存新的 HTTPS URL； - 必要时删除旧订阅后重新创建； - 自动注册型触发器停用后重新激活； - 使用平台提供的“测试回调”或“重新发送”功能验证。 --- ## 十三、安全部署时还应完成的事项 修复回调后，不要停留在“能用即可”的状态。自建 n8n 往往保存 API 密钥、数据库密码和业务数据，应至少做好以下措施。 ### 使用固定的加密密钥 配置一个足够随机且长期保存的密钥： ```yaml N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY} ``` 可以生成随机值： ```bash openssl rand -hex 32 ``` 妥善备份该密钥，不要提交到 Git 仓库，也不要在迁移时随意更换。否则已有凭据可能无法正常解密。 ### 持久化 n8n 数据目录 ```yaml volumes: - n8n_data:/home/node/.n8n ``` 同时对数据库和数据卷进行定期备份。容器可重建不等于业务数据可恢复。 ### 不直接公开 5678 让外部请求统一经过 HTTPS 反向代理，只对公网开放必要端口。 ### 限制编辑器访问 Webhook 必须被第三方平台访问，但编辑器不一定需要对整个公网开放。可以结合： - VPN； - 固定办公 IP； - 零信任访问控制； - 独立的编辑器访问策略； - n8n 自身的用户管理与强密码。 配置额外访问控制时，务必确认不会把第三方 Webhook 一起重定向到交互式登录页面。 ### 更新前先备份并查看变更说明 不要在生产环境中长期依赖不可控的自动更新。即使 Compose 示例使用了 `latest`，正式部署也更适合根据团队维护策略固定经过验证的版本，在升级前备份数据库、加密密钥和数据目录，并阅读对应版本的变更说明。 --- ## 最终核对清单 如果下面各项全部成立，n8n Webhook 通常就能稳定接收外部回调： - \[ \] 域名 A/AAAA 记录指向正确入口； - \[ \] HTTPS 证书有效、域名匹配且证书链完整； - \[ \] 公网 TCP 443 可访问； - \[ \] Nginx 能连接 n8n 的 `5678` 端口； - \[ \] 代理没有删除或错误改写 `/webhook/` 路径； - \[ \] `Host`、`X-Forwarded-For`、`X-Forwarded-Proto` 正确传递； - \[ \] `WEBHOOK_URL` 是完整的公网 HTTPS 地址； - \[ \] `N8N_HOST` 和 `N8N_PROTOCOL` 与外部地址一致； - \[ \] `N8N_PROXY_HOPS` 与实际代理链路匹配； - \[ \] 修改环境变量后已经重建容器； - \[ \] 正式回调使用 `/webhook/`，而不是 `/webhook-test/`； - \[ \] 工作流已经激活或发布； - \[ \] 请求方法、路径和鉴权配置完全一致； - \[ \] 第三方平台已经更新或重新注册回调地址； - \[ \] CDN、WAF 或统一登录没有拦截 Webhook； - \[ \] Nginx 和 n8n 日志能看到同一次请求； - \[ \] n8n 的数据目录、数据库和加密密钥已有备份。 最关键的排查原则是：**不要只看 n8n 编辑器中的 URL，也不要只看“网页能否打开”，而要从公网请求开始，沿着 DNS、HTTPS、反向代理、Docker 网络和工作流状态逐层确认。** 一旦确定请求在哪一层消失，问题通常就能快速收敛。 ### Docker 镜像瘦身与构建加速实战：多阶段构建、BuildKit 缓存与 CI 复用 URL: https://isoziyuan.com/p/100102/ Last updated: 2026-08-27T06:11:40.000Z 很多项目的 Dockerfile 一开始只有几行：复制代码、安装依赖、执行构建。它确实能运行，但随着项目增长，通常会出现以下问题： - 一个普通 Node.js 服务镜像动辄数百 MB，甚至超过 1 GB； - 修改一行源代码，却重新下载全部依赖； - 本地二次构建很快，到了 CI 环境又从零开始； - 为了编译原生依赖安装了 `gcc`、`make`，最终运行镜像也携带了这些工具； - `.env`、`.git`、测试报告甚至本地 `node_modules` 被发送进构建上下文； - 为了访问私有依赖，把 Token 写进 `ARG` 或 Dockerfile，留下安全隐患； - 换成 Alpine 后体积看似下降，却出现原生模块、字体、时区或 `glibc` 兼容问题。 这篇教程以一个“TypeScript 编译为 `dist/`、使用 npm 管理依赖的 Node.js 服务”为例，完整演示如何通过多阶段构建、BuildKit 缓存挂载和远程缓存优化镜像体积及构建速度。 虽然示例使用 Node.js，但其中的分层原则同样适用于 Go、Java、Python、Rust 和前端静态站点。 ## 一、先理解优化目标 Docker 镜像优化并不等于单纯选择最小的基础镜像。真正需要同时关注的是以下四点。 ### 1\. 缩小最终运行镜像 运行镜像通常只需要： - 运行时； - 生产依赖； - 编译产物； - 必要的配置和系统动态库。 它通常不需要： - TypeScript 源码； - 单元测试； - 开发依赖； - 编译器和构建工具； - npm 缓存； - Git 历史； - CI 配置。 ### 2\. 提高 Docker 层缓存命中率 Docker 构建缓存以指令和相关文件内容为依据。下面这种顺序会让缓存非常脆弱： ```dockerfile COPY . . RUN npm install ``` 任意源代码发生变化，`COPY . .` 对应的层都会变化，于是后面的依赖安装也必须重新执行。 更合理的顺序是： ```dockerfile COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build ``` 只要依赖清单没有变化，修改业务源码就不会让依赖安装层失效。 ### 3\. 让依赖下载缓存脱离普通镜像层 普通层缓存失效后，`npm ci` 仍可能需要重新执行。但使用 BuildKit 缓存挂载后，npm 已下载的软件包可以继续复用： ```dockerfile RUN --mount=type=cache,target=/root/.npm \ npm ci ``` 需要注意： - `npm ci` 这条指令仍会运行； - `/root/.npm` 中的下载缓存可以复用； - 缓存目录不会被写入最终镜像； - 这与直接把 npm 缓存复制进镜像完全不同。 ### 4\. 让 CI 也能复用缓存 开发者电脑上的本地缓存不会自动出现在新的 CI Runner 中。要解决这一问题，需要把 BuildKit 缓存导出到： - 容器镜像仓库； - CI 平台提供的缓存后端； - 本地持久化目录； - 其他 BuildKit 支持的缓存存储。 本文使用通用性较强的镜像仓库缓存作为主要方案。 --- ## 二、准备工作 ### 1\. 环境要求 建议准备： - 较新的 Docker Engine 或 Docker Desktop； - Docker Buildx； - 项目中存在 `package-lock.json`； - 项目能够通过 `npm run build` 生成 `dist/`； - 应用可以通过 `node dist/server.js` 启动。 检查 Buildx： ```bash docker buildx version docker buildx ls ``` 如果还没有可用的 Buildx Builder，可以创建一个： ```bash docker buildx create \ --name app-builder \ --driver docker-container \ --use docker buildx inspect --bootstrap ``` `docker-container` 驱动通常更适合使用多平台构建和完整的外部缓存导出功能。 ### 2\. 示例项目约定 示例假设 `package.json` 至少包含类似脚本： ```json { "scripts": { "build": "tsc", "start": "node dist/server.js" } } ``` 目录结构类似： ```text . ├── src/ ├── package.json ├── package-lock.json ├── tsconfig.json ├── Dockerfile └── .dockerignore ``` 如果你的项目是 Next.js、Nuxt、NestJS、Vite SSR 或其他框架，需要按照实际产物调整： - 构建输出目录； - 启动文件； - 是否需要复制静态资源； - 是否需要生产依赖； - 是否有框架专用的独立输出模式。 不要机械地把本文的 `dist/server.js` 套到所有项目上。 --- ## 三、问题 Dockerfile：为什么又慢又大 很多项目最初使用下面这样的 Dockerfile： ```dockerfile FROM node:24-bookworm WORKDIR /app COPY . . RUN npm install RUN npm run build EXPOSE 3000 CMD ["npm", "start"] ``` 它存在几个明显问题： 1. `COPY . .` 在安装依赖之前执行，业务代码变化会导致依赖层失效； 2. 使用 `npm install`，不如 `npm ci` 适合基于锁文件的可重复构建； 3. 开发依赖保留在最终镜像中； 4. 源代码、测试文件和构建配置全部保留； 5. 完整 Debian 基础镜像比 `slim` 版本包含更多非必要组件； 6. 如果构建时安装了编译工具，它们也会进入运行镜像； 7. 没有使用 BuildKit 缓存挂载； 8. 默认以 root 用户运行应用； 9. 如果没有 `.dockerignore`，构建上下文可能非常大。 先保留这个版本用于对照： ```bash time docker buildx build \ --load \ --progress=plain \ -f Dockerfile.before \ -t demo-app:before \ . ``` 这里使用 `--load`，是因为 `docker-container` 驱动默认不会自动把结果加载到本地 Docker 镜像列表中。 --- ## 四、第一步：编写 `.dockerignore` 在优化 Dockerfile 之前，应先控制构建上下文。 创建 `.dockerignore`： ```dockerignore # 本地依赖与构建产物 node_modules dist coverage # Git 与编辑器文件 .git .gitignore .vscode .idea # 日志 *.log npm-debug.log* # 本地环境变量，避免敏感配置进入构建上下文 .env .env.* !.env.example # 测试及缓存目录，请按项目实际情况调整 .nyc_output .cache .tmp # 本地 Buildx 缓存 .buildx-cache .buildx-cache-* # 编排和说明文件通常不需要进入镜像 compose*.yml docker-compose*.yml README* ``` 如果构建过程确实依赖 README、测试文件或某个配置目录，就不能直接忽略它们。 检查构建日志中的上下文大小： ```bash docker buildx build \ --load \ --progress=plain \ -t demo-app:context-test \ . ``` 日志中会出现类似 `transferring context` 的信息。项目根目录下如果有几百 MB 的本地依赖，而 `.dockerignore` 又没有排除它们，每次构建都会浪费时间传输上下文。 > `.dockerignore` 不只是体积优化手段，也是安全边界。未被 `COPY` 的文件不一定会出现在最终镜像中，但它们仍可能被发送给构建器。 --- ## 五、第二步：使用多阶段构建拆分依赖、编译与运行环境 下面是一份可直接修改使用的优化版 Dockerfile。 ```dockerfile # syntax=docker/dockerfile:1 # 使用参数集中管理基础镜像版本。 # 正式生产环境还可以进一步固定到经过验证的 sha256 摘要。 ARG NODE_IMAGE=node:24-bookworm-slim # ------------------------------------------------------------ # 阶段一：安装完整依赖，包括构建所需的 devDependencies # ------------------------------------------------------------ FROM ${NODE_IMAGE} AS deps WORKDIR /app # 先只复制依赖清单。 # 业务源码变化时，只要锁文件未变化，这一层就能继续命中缓存。 COPY package.json package-lock.json ./ # npm 下载缓存保存在 BuildKit 缓存中，不写入镜像层。 # sharing=locked 可减少并行构建同时写缓存时的冲突。 RUN --mount=type=cache,id=npm-cache,target=/root/.npm,sharing=locked \ npm ci # ------------------------------------------------------------ # 阶段二：执行项目编译 # ------------------------------------------------------------ FROM ${NODE_IMAGE} AS build WORKDIR /app # 复用上一阶段安装好的完整依赖。 COPY --from=deps /app/node_modules ./node_modules # 此时再复制源码，避免源码改动影响依赖安装缓存。 COPY . . RUN npm run build # ------------------------------------------------------------ # 阶段三：只安装生产依赖 # ------------------------------------------------------------ FROM ${NODE_IMAGE} AS prod-deps WORKDIR /app COPY package.json package-lock.json ./ # --omit=dev 排除开发依赖。 RUN --mount=type=cache,id=npm-cache,target=/root/.npm,sharing=locked \ npm ci --omit=dev # ------------------------------------------------------------ # 阶段四：最终运行镜像 # ------------------------------------------------------------ FROM ${NODE_IMAGE} AS runtime WORKDIR /app ENV NODE_ENV=production # 只复制生产依赖、依赖描述文件和编译产物。 # --chown 确保非 root 用户能够正常访问文件。 COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules COPY --chown=node:node package.json package-lock.json ./ COPY --from=build --chown=node:node /app/dist ./dist # 如果项目还需要 public、views、prisma 等运行时文件， # 应继续使用 COPY --from=build 有选择地复制。 # # 例如： # COPY --from=build --chown=node:node /app/public ./public USER node EXPOSE 3000 CMD ["node", "dist/server.js"] ``` ### 为什么要分成四个阶段 #### `deps` 阶段 安装所有依赖，包括 TypeScript、打包器、测试编译插件等开发依赖，供编译使用。 #### `build` 阶段 复制源码并执行编译。源码变更一般只会使这一阶段及其后续阶段失效。 #### `prod-deps` 阶段 单独安装生产依赖，避免把 `devDependencies` 带入最终镜像。 不能简单地认为： ```bash npm prune --omit=dev ``` 在所有项目中都一定比重新执行 `npm ci --omit=dev` 更可靠。单独安装生产依赖通常更清晰，也更容易保证最终内容符合锁文件。 #### `runtime` 阶段 最终镜像只接收运行时需要的内容。前面阶段中的源码、编译器、npm 下载缓存等都不会自动进入这个阶段。 这也是多阶段构建最核心的价值：**构建环境可以复杂，运行环境必须克制。** --- ## 六、第三步：构建并验证缓存效果 ### 1\. 第一次构建 ```bash time docker buildx build \ --load \ --progress=plain \ -t demo-app:optimized \ . ``` 第一次构建需要下载基础镜像和 npm 依赖，通常不会特别快。 ### 2\. 不修改代码，再构建一次 ```bash time docker buildx build \ --load \ --progress=plain \ -t demo-app:optimized \ . ``` 日志中多数步骤应该显示 `CACHED`。 ### 3\. 只修改业务源码 例如修改： ```text src/server.ts ``` 然后重新构建： ```bash time docker buildx build \ --load \ --progress=plain \ -t demo-app:optimized \ . ``` 正常情况下： - `COPY package.json package-lock.json` 命中缓存； - `npm ci` 命中普通层缓存； - `COPY . .` 及 `npm run build` 重新执行； - 生产依赖阶段继续命中缓存。 ### 4\. 修改锁文件后测试 安装一个依赖： ```bash npm install some-package ``` 再次构建时，依赖安装层会失效并重新执行。不过由于 `/root/.npm` 使用了 BuildKit 缓存挂载，已经下载过的软件包仍有机会被复用，从而减少网络下载。 --- ## 七、第四步：检查镜像体积与分层 ### 1\. 比较镜像大小 ```bash docker image ls demo-app ``` 也可以查看原始字节数： ```bash docker image inspect demo-app:before \ --format '{{.Size}} bytes' docker image inspect demo-app:optimized \ --format '{{.Size}} bytes' ``` 不要直接套用网上“从 1 GB 降到 100 MB”之类的数据。实际大小取决于： - 基础镜像； - 生产依赖数量； - 是否包含浏览器、字体或机器学习模型； - 是否存在原生模块； - 编译产物大小； - CPU 架构； - 本地显示的是解压后层大小，还是仓库传输时的压缩大小。 建议记录自己的真实结果： | 项目 | 优化前 | 优化后 | | --------- | ---- | ---- | | 镜像大小 | 实测填写 | 实测填写 | | 首次构建耗时 | 实测填写 | 实测填写 | | 未改代码二次构建 | 实测填写 | 实测填写 | | 只改业务代码后构建 | 实测填写 | 实测填写 | ### 2\. 查看每一层的大小 ```bash docker history demo-app:optimized ``` 需要更完整的指令信息时： ```bash docker history --no-trunc demo-app:optimized ``` 重点检查： - 是否存在异常大的 `COPY` 层； - 是否把整个项目复制进了运行阶段； - 是否把 npm 缓存复制进镜像； - 是否在某一层创建大文件、下一层才删除。 Docker 镜像是分层的。下面的操作不能真正消除上一层中的文件： ```dockerfile RUN download-big-file RUN rm -f big-file ``` 因为大文件已经存在于前一层。应改为同一条指令中下载、使用并删除： ```dockerfile RUN download-big-file \ && use-big-file \ && rm -f big-file ``` 更好的做法通常是让大文件只存在于构建阶段，最终阶段根本不复制它。 --- ## 八、第五步：运行容器并做冒烟测试 构建完成后，不要只看镜像大小，还要实际运行： ```bash docker run --rm \ --init \ -p 3000:3000 \ -e PORT=3000 \ demo-app:optimized ``` 另开终端测试： ```bash curl http://127.0.0.1:3000/ ``` 应用在容器中应监听： ```text 0.0.0.0 ``` 而不是只监听： ```text 127.0.0.1 ``` 否则即使端口映射正确，宿主机也可能无法访问容器中的服务。 `--init` 会为容器添加轻量级 init 进程，帮助转发信号和回收孤儿进程。生产环境也可以在 Compose、Kubernetes 或运行命令中配置对应能力，而不一定要把额外 init 工具安装进镜像。 --- ## 九、BuildKit 缓存挂载的正确用法 ### 1\. npm 缓存 ```dockerfile RUN --mount=type=cache,target=/root/.npm \ npm ci ``` 缓存的是 npm 下载目录，而不是直接缓存最终的 `node_modules`。 通常不建议把跨构建共享缓存直接挂载到 `/app/node_modules`，因为： - 可能残留已经从锁文件删除的包； - 不同 Node.js 版本之间可能不兼容； - 原生模块可能与 CPU 架构或 libc 不匹配； - 容易让构建结果依赖缓存历史，降低可重复性。 `npm ci` 根据锁文件创建干净依赖树，再利用 npm 下载缓存，通常更稳妥。 ### 2\. apt 缓存 如果 Node.js 原生模块需要 `python3`、`make`、`g++`，应只在依赖构建阶段安装。 示例： ```dockerfile FROM node:24-bookworm-slim AS native-deps WORKDIR /app # Debian 官方容器镜像可能包含自动清理 apt 缓存的配置。 # 如果确实希望 BuildKit 缓存 deb 包，可移除该配置。 RUN rm -f /etc/apt/apt.conf.d/docker-clean RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ --mount=type=cache,target=/var/lib/apt,sharing=locked \ apt-get update \ && apt-get install -y --no-install-recommends \ python3 \ make \ g++ COPY package.json package-lock.json ./ RUN --mount=type=cache,target=/root/.npm,sharing=locked \ npm ci ``` 这些编译工具只应该出现在构建阶段，最终 `runtime` 阶段仍从干净的基础镜像开始。 如果某个原生模块在运行时依赖系统动态库，例如图像处理、数据库客户端或字体库，则必须把对应的**运行时库**安装到最终镜像中。只复制 `node_modules` 并不能自动复制其依赖的系统库。 ### 3\. 查看和清理 Buildx 缓存 查看缓存占用： ```bash docker buildx du ``` 清理当前 Builder 的未使用缓存： ```bash docker buildx prune ``` 无交互清理： ```bash docker buildx prune -f ``` 不要把定期清理缓存理解为常规加速手段。缓存被删除后，下一次构建自然会变慢。通常只在磁盘压力大或排查异常缓存时清理。 --- ## 十、第六步：让 CI 使用镜像仓库远程缓存 本地二次构建快，并不代表 CI 也快。临时 Runner 每次启动时可能没有任何本地缓存。 可以把 BuildKit 缓存导出到镜像仓库中的独立引用。 先登录仓库： ```bash docker login registry.example.com ``` 设置变量： ```bash IMAGE_REF=registry.example.com/team/demo-app CACHE_REF=registry.example.com/team/demo-app:buildcache ``` 执行构建： ```bash docker buildx build \ --platform linux/amd64 \ --cache-from=type=registry,ref=${CACHE_REF} \ --cache-to=type=registry,ref=${CACHE_REF},mode=max \ --tag ${IMAGE_REF}:latest \ --push \ . ``` 参数含义： - `--cache-from`：尝试从远程缓存读取可复用层； - `--cache-to`：将本次构建缓存写回仓库； - `mode=max`：尽量导出包括中间阶段在内的缓存； - `--push`：把最终镜像推送到仓库； - 缓存引用与正式镜像标签分开管理。 如果只是本地测试，不推送镜像： ```bash docker buildx build \ --cache-from=type=registry,ref=${CACHE_REF} \ --cache-to=type=registry,ref=${CACHE_REF},mode=max \ --load \ --tag demo-app:local \ . ``` 不过，此命令仍需要： - 已登录对应仓库； - 对缓存引用具有拉取和推送权限； - 仓库能够保存 BuildKit 导出的缓存制品。 ### 多平台构建 如果需要同时发布 AMD64 和 ARM64： ```bash docker buildx build \ --platform linux/amd64,linux/arm64 \ --cache-from=type=registry,ref=${CACHE_REF} \ --cache-to=type=registry,ref=${CACHE_REF},mode=max \ --tag ${IMAGE_REF}:latest \ --push \ . ``` 多平台结果通常应使用 `--push` 推送到仓库。普通 Docker 本地镜像存储一般不能通过一次 `--load` 接收完整的多平台镜像索引。 --- ## 十一、不使用镜像仓库时的本地目录缓存 某些自建 CI 可以持久化工作目录，此时可以使用本地缓存： ```bash docker buildx build \ --cache-from=type=local,src=.buildx-cache \ --cache-to=type=local,dest=.buildx-cache-next,mode=max \ --load \ --tag demo-app:local \ . ``` 构建成功后替换缓存目录： ```bash rm -rf .buildx-cache mv .buildx-cache-next .buildx-cache ``` 不要同时把同一个目录直接作为输入和输出，以免出现缓存布局冲突或无效累积。 同时确保 `.dockerignore` 包含： ```dockerignore .buildx-cache .buildx-cache-* ``` 否则缓存目录可能被重新发送进 Docker 构建上下文，形成越构建上下文越大的问题。 --- ## 十二、私有 npm 仓库：不要把 Token 写进镜像 错误做法： ```dockerfile ARG NPM_TOKEN RUN echo "//registry.example.com/:_authToken=${NPM_TOKEN}" > /root/.npmrc \ && npm ci ``` 即使后续删除 `.npmrc`，敏感信息仍可能出现在： - 镜像历史； - 构建元数据； - 某个中间层； - CI 日志； - Builder 缓存。 应使用 BuildKit Secret。 Dockerfile 中写成： ```dockerfile RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \ --mount=type=cache,target=/root/.npm,sharing=locked \ npm ci ``` 构建时传入本机的 `.npmrc`： ```bash docker buildx build \ --secret id=npmrc,src="${HOME}/.npmrc" \ --load \ -t demo-app:private \ . ``` Secret 只在该条 `RUN` 指令执行期间挂载，不会因为普通 `COPY` 自动进入镜像层。 需要特别注意：Secret 内容变化通常不会像普通文件那样自动使构建层失效。如果私有依赖版本发生变化，应同时更新锁文件，或者有针对性地使对应阶段重新执行。 --- ## 十三、基础镜像应该怎么选 ### 1\. 不要只看标签中的“最小” 常见选择包括： ```dockerfile FROM node:24-bookworm FROM node:24-bookworm-slim FROM node:24-alpine ``` 通常可以先尝试 `bookworm-slim`，因为它在镜像体积和兼容性之间较为平衡。 ### 2\. Alpine 不一定是最优解 Alpine 使用 musl libc，而很多预编译原生模块以 glibc 环境为主要目标。切换到 Alpine 后可能遇到： - 原生模块没有对应预编译包，需要现场编译； - 编译时间增加； - 某些二进制程序无法直接运行； - 字体、时区、证书或系统工具需要额外安装； - 为解决兼容问题安装大量软件，抵消了体积优势。 因此，是否使用 Alpine 应通过实际依赖、构建时间和运行测试决定，而不是只比较空基础镜像大小。 ### 3\. 正式环境考虑固定镜像摘要 标签对应内容可能随着上游更新发生变化。需要高可重复性时，可以在验证后固定摘要： ```dockerfile FROM node:24-bookworm-slim@sha256:实际验证过的摘要 ``` 不要复制文档中的虚构摘要。应从实际仓库查询： ```bash docker buildx imagetools inspect node:24-bookworm-slim ``` 固定摘要后，基础镜像不会自动获得上游更新，因此还需要建立定期更新、重建和安全验证机制。 --- ## 十四、缓存命中率低时的排查顺序 ### 问题 1：每次修改源码都重新执行 `npm ci` 检查 Dockerfile 是否写成： ```dockerfile COPY . . RUN npm ci ``` 应改为： ```dockerfile COPY package.json package-lock.json ./ RUN npm ci COPY . . ``` 同时确认依赖清单没有被脚本自动改写。 ### 问题 2：明明没改文件，`COPY . .` 仍然失效 重点检查： - 是否生成了日志文件； - 是否生成了覆盖率报告； - 是否把 `.git` 发送进上下文； - 是否有工具修改了配置文件； - 是否存在未忽略的本地缓存； - CI 是否在工作目录中写入构建编号或时间戳； - 是否每次都生成不同内容的文件。 使用下面的命令查看详细过程： ```bash docker buildx build \ --load \ --progress=plain \ -t demo-app:debug \ . ``` ### 问题 3：BuildKit 缓存挂载没有减小镜像 这是正常现象。缓存挂载主要用于加快下载和构建，本身不一定直接改变最终镜像大小。 镜像体积主要由这些措施决定： - 多阶段构建； - 只复制运行文件； - 排除开发依赖； - 选择合适的基础镜像； - 避免把缓存、源码和工具链放进运行阶段。 ### 问题 4：使用 `USER node` 后出现 `EACCES` 通常是目录权限问题。复制文件时使用： ```dockerfile COPY --chown=node:node ... ``` 如果应用需要写入目录，可以预先创建并修改权限： ```dockerfile RUN mkdir -p /app/data \ && chown -R node:node /app/data ``` 不要为了省事退回 root 用户运行。 ### 问题 5：容器中提示找不到某个模块 可能原因包括： - 该模块被错误放在 `devDependencies` 中，但运行时仍需要； - 编译产物动态引用了源码目录； - 生产依赖阶段未执行安装脚本； - monorepo 中只复制了根目录锁文件，没有复制 Workspace 所需清单； - 构建工具把外部依赖保留为运行时依赖。 先在本地执行： ```bash npm ci --omit=dev node dist/server.js ``` 如果宿主机上也失败，应先修复依赖分类，而不是修改 Docker 缓存。 ### 问题 6：出现共享库缺失错误 典型形式： ```text error while loading shared libraries ``` 或者原生模块加载失败。 说明 `node_modules` 中的原生二进制依赖某些系统运行库。应在最终运行阶段安装必要的运行库，而不是把整个编译环境复制进去。 还要确保构建阶段和运行阶段使用兼容的： - Linux 发行版； - libc； - CPU 架构； - Node.js ABI。 ### 问题 7：出现 `exec format error` 常见原因是镜像架构与运行机器不一致，例如在 ARM64 环境构建了 ARM64 镜像，却部署到 AMD64 服务器。 明确指定目标平台： ```bash docker buildx build \ --platform linux/amd64 \ --load \ -t demo-app:amd64 \ . ``` 如果进行跨架构构建，含原生依赖的项目还应进行真实目标架构测试，不能只保证构建命令成功。 ### 问题 8：构建成功但本地看不到镜像 使用 `docker-container` 驱动时，需要显式指定输出： ```bash docker buildx build --load -t demo-app:local . ``` 或推送到仓库： ```bash docker buildx build --push -t registry.example.com/team/demo-app:latest . ``` ### 问题 9：`npm ci` 提示锁文件不一致 `npm ci` 要求 `package.json` 与 `package-lock.json` 一致。 在开发环境重新安装并提交锁文件： ```bash npm install git add package.json package-lock.json git commit -m "更新依赖锁文件" ``` 不要在 Dockerfile 中改回 `npm install` 来掩盖锁文件问题。 ### 问题 10：想完全重新构建某个阶段 绕过普通层缓存： ```bash docker buildx build \ --no-cache \ --load \ -t demo-app:clean \ . ``` 如果只想让特定阶段不使用普通层缓存，可以在支持该参数的 Buildx 版本中使用： ```bash docker buildx build \ --no-cache-filter build \ --load \ -t demo-app:rebuild \ . ``` `--no-cache` 主要针对构建层缓存。缓存挂载是独立机制；若怀疑缓存目录本身异常，可以单独执行 `docker buildx prune`，但这会影响之后的构建速度。 --- ## 十五、进一步提升构建速度的原则 ### 1\. 把变化频率低的步骤放在前面 推荐顺序： 1. 基础镜像； 2. 系统依赖； 3. 依赖清单； 4. 安装项目依赖； 5. 复制源码； 6. 执行编译； 7. 复制运行产物。 越靠前的层，越应该稳定。 ### 2\. 不要滥用缓存破坏参数 下面这种方式会强制后续缓存失效： ```dockerfile ARG CACHE_BUST RUN echo "$CACHE_BUST" ``` 它适合临时排查，不适合日常构建。缓存问题应通过合理的依赖输入和阶段边界解决。 ### 3\. 区分“检查基础镜像更新”和“完全禁用缓存” 构建时增加： ```bash docker buildx build --pull ... ``` 表示检查并拉取更新后的基础镜像，不等于禁用所有构建缓存。 完全绕过层缓存使用： ```bash docker buildx build --no-cache ... ``` 二者用途不同。 ### 4\. 不要把运行时配置烘焙进镜像 环境相关配置应尽量在运行容器时注入： ```bash docker run \ -e DATABASE_URL="..." \ -e NODE_ENV=production \ demo-app:optimized ``` 不要为测试、预发布和生产分别把 `.env` 复制进镜像。这不仅会降低镜像复用率，也可能泄露敏感信息。 ### 5\. 镜像优化后仍要做功能和安全验证 更小的镜像通常意味着更少的软件包和更小的攻击面，但“体积更小”不等于“没有漏洞”。 优化后至少应验证： - 应用启动； - 健康检查接口； - 文件写入权限； - 优雅退出； - 数据库和外部服务连接； - 原生模块加载； - 目标 CPU 架构； - 基础镜像与依赖安全更新。 --- ## 十六、最终检查清单 在提交 Dockerfile 前，可以逐项确认： - \[ \] 已创建 `.dockerignore`； - \[ \] 没有把 `.git`、`.env`、本地 `node_modules` 发进构建上下文； - \[ \] 使用锁文件和 `npm ci`； - \[ \] 依赖清单在业务源码之前复制； - \[ \] 编译阶段与运行阶段分离； - \[ \] 最终镜像中没有开发依赖； - \[ \] 最终镜像中没有编译器和构建工具； - \[ \] 使用 BuildKit 缓存挂载复用包管理器下载缓存； - \[ \] CI 配置了持久化或远程缓存； - \[ \] 私有仓库凭据通过 BuildKit Secret 传入； - \[ \] 应用不以 root 用户运行； - \[ \] 已执行容器启动和接口冒烟测试； - \[ \] 已检查镜像分层和真实体积； - \[ \] 已验证目标平台及原生依赖兼容性； - \[ \] 没有为了追求更小体积而盲目切换 Alpine。 ## 总结 优化 Docker 镜像体积和构建速度，最有效的方法不是堆叠复杂参数，而是建立清晰的构建边界： 1. 用 `.dockerignore` 缩小构建上下文并阻止敏感文件进入构建器； 2. 先复制锁文件、后复制源码，提高依赖层缓存命中率； 3. 用多阶段构建分离开发依赖、编译产物和运行环境； 4. 用 BuildKit `cache mount` 复用 npm、apt 等下载缓存； 5. 用远程缓存解决临时 CI Runner 每次从零构建的问题； 6. 用 BuildKit Secret 安全传递私有仓库凭据； 7. 最终镜像只保留运行时、生产依赖和必要产物； 8. 通过真实构建耗时、镜像大小和运行测试验证效果。 一份优秀的 Dockerfile 不只是“能构建”，还应该具备缓存稳定、产物精简、凭据安全、结果可重复和运行环境最小化等特征。先完成多阶段构建和依赖分层，再引入 BuildKit 缓存与 CI 远程缓存，通常就能同时解决镜像臃肿和构建缓慢这两个最常见的问题。 ### 2026 年便宜 VPS 选购指南：配置、线路、价格与续费避坑 URL: https://isoziyuan.com/p/100101/ Last updated: 2026-08-27T05:13:10.000Z 便宜 VPS 并不是价格越低越值得买。CPU 是否超售、内存有没有限制、硬盘是本地 NVMe 还是共享存储、带宽能否跑满、回国线路是否绕路，往往比纸面上的“2 核 2G”更重要。 本文按 **2026 年 8 月**的选购环境整理，适合建站、个人开发、代理出口、远程开发、监控节点及轻量服务部署。需要特别说明：VPS 套餐的价格、库存、线路、退款规则和促销活动变化很快，文中的价格仅作为市场区间参考，购买前必须在服务商官网重新核对最终账单、续费金额和服务条款。 ## 一、先确定需求，不要看到低价就下单 购买 VPS 前，先回答以下几个问题： 1. 用户主要位于中国大陆、港澳台，还是海外？ 2. 用来建站、运行 Docker、做远程开发，还是只部署监控和脚本？ 3. 是否需要独立 IPv4？ 4. 每月预计使用多少流量？ 5. 能否接受晚高峰延迟升高或丢包？ 6. 是否需要快照、备份、DDoS 防护和工单支持？ 7. 是准备使用一个月，还是长期续费？ 如果需求没有明确，最容易出现两种结果：一是为所谓“优化线路”支付过高费用；二是买到极便宜的年付 VPS，却因为网络不可用、磁盘性能差而闲置。 ### 常见场景的建议起步配置 | 使用场景 | 建议起步配置 | 更应该关注的项目 | | ----------------- | --------------------- | ----------------- | | 探针、DDNS、轻量脚本 | 1 核、512MB～1GB、10GB 磁盘 | 稳定性、IPv4/IPv6、续费价 | | 静态网站、个人博客 | 1～2 核、1～2GB、20GB 以上 | 磁盘延迟、备份、线路 | | WordPress、小型数据库 | 2 核、2～4GB、40GB 以上 | CPU 单核、内存、磁盘 IOPS | | Docker 多容器 | 2～4 核、4GB 以上 | 内存、磁盘空间、CPU 限制 | | Java、Node.js 开发环境 | 2 核、4GB 以上 | 内存、CPU 持续性能 | | 跨境网站或 API | 2 核、2GB 以上 | 目标地区线路、SLA、流量 | | 流媒体转码 | 4 核以上 | CPU 指令集、持续占用规则 | | 游戏服务器 | 高主频 2～4 核、4GB 以上 | 单核性能、DDoS 防护、延迟 | “能启动”不等于“能稳定运行”。例如，1GB 内存确实可以安装 WordPress，但同时运行数据库、PHP-FPM、Web 服务和系统更新时，很容易触发 OOM。长期使用时应保留至少 20%～30% 的内存余量。 ## 二、便宜 VPS 的价格应该怎么看 下面是低价 VPS 市场中较常见的价格区间，不代表任何厂商在 2026 年 8 月一定有对应库存，也不是实时优惠报价。 | 产品类型 | 常见参考区间 | 典型配置 | 主要特点 | | ------------- | ------------- | ------------------- | --------------------- | | 海外年付促销 VPS | 10～30 美元/年 | 1～2 核、1～2GB、10～40GB | 价格低，但超售、续费和线路风险较高 | | 海外常规入门云主机 | 4～8 美元/月 | 1 核、1GB、20～30GB | 按小时或按月计费，管理方便 | | 欧洲高性价比云主机 | 3～8 欧元/月 | 2 核、2～4GB、40GB 左右 | 配置通常较高，但中国方向线路一般 | | 中国大陆轻量服务器 | 促销常见为几十至数百元/年 | 2 核、2～4GB | 国内访问好，但通常需要实名，建站可能要备案 | | 香港、日本、新加坡普通线路 | 5～15 美元/月 | 1～2 核、1～2GB | 延迟较低，但晚高峰不一定稳定 | | 中国方向优化线路 VPS | 10～30 美元/月或更高 | 1～2 核、1～2GB | 流量通常较少，线路标签和实际路由必须核验 | 判断价格时，应计算**长期总成本**： > 两年总成本 = 首期价格 + 续费价格 + IPv4 费用 + 备份费用 + 超额流量费用 + 税费 例如，首年极低价的 VPS，如果第二年恢复高价，可能还不如从一开始购买月付实例。欧盟地区服务商还可能根据账户所在地收取 VAT；部分厂商单独收取 IPv4、快照或备份费用。结账页面显示的最终价格才有参考意义。 ## 三、CPU：不要只看“几核” VPS 的 vCPU 通常不是独享物理核心。很多便宜 VPS 会在同一台宿主机上分配大量虚拟 CPU，因此“4 核低价机”不一定比“2 核普通云主机”快。 ### 1\. CPU 型号和代际 优先关注： - 是否公布 CPU 型号或平台代际； - 单核频率和实际单线程性能； - 是否支持 AES、AVX、AVX2 等指令集； - 是 Intel、AMD x86，还是 ARM； - 是否对持续高负载进行限速。 新一代 AMD EPYC 和 Intel Xeon 平台通常有更好的每核性能，但型号只是参考。宿主机负载、CPU 调度比例和超售程度会直接影响实际表现。 ARM VPS 在编译、Web 服务和容器场景中可能很划算，但购买前应确认软件镜像及 Docker 镜像是否支持 `arm64`。只提供 `amd64` 二进制文件的应用无法直接运行。 ### 2\. 共享核、突发核与独享核 - **共享 vCPU**：适合网站、开发和间歇任务，不适合长期满载。 - **突发型 CPU**：空闲时性能较好，持续使用可能受积分或公平使用策略限制。 - **独享 vCPU**：价格更高，适合编译、数据库、游戏服和持续计算。 如果厂商只写“4 vCPU”，却没有说明 CPU 使用政策，不要默认它可以长期跑满四核。持续转码、挖矿、压力测试等行为可能触发限速或停机。 ### 3\. 检查 CPU 与虚拟化环境 登录后可执行： ```bash lscpu nproc systemd-detect-virt cat /proc/cpuinfo | grep "model name" | head ``` 观察系统负载和 CPU steal： ```bash top ``` `top` 中的 `st` 表示虚拟机等待宿主机分配 CPU 的时间。短时波动不一定有问题，但在业务高峰期长期偏高，通常意味着宿主机竞争明显。 如需测试单核性能，可安装 `sysbench` 后运行： ```bash sysbench cpu --threads=1 --time=30 run ``` 建议在不同时间段重复测试，不要只依据开机后的单次跑分。 ## 四、内存：容量、Swap 和突发限制都要看 ### 1\. 真实内存与 Swap KVM VPS 通常会分配相对明确的内存容量，但仍要关注是否存在 ballooning、突发内存或特殊限制。部分廉价容器型产品的内存策略可能更加严格。 检查方式： ```bash free -h cat /proc/meminfo | head ``` Swap 不能代替物理内存。磁盘 Swap 可以降低进程因内存不足被直接杀死的概率，但频繁交换会导致明显卡顿。数据库和 Java 应用尤其不能依赖 Swap 维持正常性能。 ### 2\. 选多大内存 - 512MB：只适合极轻量脚本或经过精简的系统； - 1GB：可部署静态站点、探针和轻量代理； - 2GB：个人博客、小型数据库的实用起点； - 4GB：适合 Docker、多服务及开发环境； - 8GB 以上：更适合 Java、大型数据库和构建任务。 还要确认控制面板的资源占用。安装带数据库、邮件、杀毒扫描的完整面板后，1GB VPS 往往没有多少可用空间。 ## 五、磁盘：NVMe 标签不等于稳定高性能 便宜 VPS 常见的磁盘类型包括： - 本地 HDD； - 本地 SATA SSD； - 本地 NVMe； - 网络块存储； - Ceph 等分布式存储。 本地 NVMe 通常延迟较低，但宿主机故障时恢复难度可能更大；分布式存储冗余能力较好，但性能受网络和集群负载影响。不能仅凭“NVMe”三个字判断质量。 ### 需要关注的指标 1. 4K 随机读写性能； 2. 磁盘延迟； 3. 持续写入是否限速； 4. 是否有 IOPS 或吞吐量上限； 5. 快照和备份是否另收费； 6. 系统盘是否可扩容； 7. 删除实例后快照是否保留。 可使用 `fio` 进行简单测试，但测试会产生大量 I/O，必须先阅读厂商的公平使用政策。不要在生产数据库所在磁盘直接压测。 ```bash fio --name=randrw \ --filename=/root/fio-test.bin \ --size=1G \ --bs=4k \ --rw=randrw \ --rwmixread=70 \ --iodepth=32 \ --direct=1 \ --runtime=60 \ --time_based \ --group_reporting ``` 完成后删除测试文件： ```bash rm -f /root/fio-test.bin ``` 年付低价 VPS 如果只提供 10GB～20GB 磁盘，还要预留系统日志、软件更新和 Docker 镜像空间。磁盘占用超过 90% 后，数据库和系统服务都可能异常。 ## 六、网络带宽：100Mbps 不等于随时能跑满 VPS 套餐中的网络规格通常由三个部分组成： - 端口速率，例如 100Mbps、1Gbps； - 月流量，例如 1TB、3TB； - 超额后的处理方式，例如停机、限速或按量计费。 ### 1\. 带宽和流量不是一回事 100Mbps 表示理论瞬时速度，大约相当于每秒 12.5MB；1TB 流量表示一个计费周期内的数据总量。 如果 100Mbps 持续跑满，一个月消耗的流量远超普通低价套餐额度。因此，高端口配合较小流量并不矛盾，它只是允许短时高速传输。 ### 2\. 共享端口与独享带宽 低价 VPS 的 1Gbps 端口通常是宿主机或机柜共享，不代表每台实例都能稳定占用 1Gbps。晚高峰速度下降可能来自： - 宿主机共享端口拥塞； - 数据中心上游拥塞； - 国际出口拥塞； - 运营商互联质量差； - 服务商对单实例限速； - TCP 单线程受延迟和丢包影响。 ### 3\. 流量统计规则 购买前应确认： - 只计算出站，还是入站和出站都计算； - 流量按自然月还是账单周期重置； - 超量后是停机、限速还是收费； - 重装系统是否重置流量； - 是否有每日流量或持续占用限制； - DDoS 攻击流量是否计费。 不能想当然地认为“每月 2TB”只计算出站。具体规则以厂商当前服务条款为准。 ## 七、VPS 线路怎么看：CN2、CMI 和 BGP 不能只看标签 对于中国大陆用户，机房距离只是影响延迟的一个因素。洛杉矶可能比某些绕路的香港节点更稳定，日本节点也可能因为运营商互联问题在晚高峰严重丢包。 ### 常见线路概念 - **普通国际线路**：成本低，晚高峰可能拥塞； - **CN2 GT**：通常部分路径接入 CN2，但不等同于全程优化； - **CN2 GIA**：一般属于更高优先级的中国电信国际线路，价格较高； - **CMI**：中国移动国际网络，部分香港、日本和新加坡节点对移动用户表现较好； - **AS9929**：常被用于描述联通方向的精品网络，但仍需核验具体路由； - **AS4837**：常见联通骨干路径，实际体验取决于地区与拥塞情况； - **BGP**：只表示使用边界网关协议或多线路接入，不自动代表优质线路； - **三网优化**：属于营销概括，电信、联通和移动的去程与回程可能完全不同。 线路可能因上游调整而变化。即使产品名称保留“优化线路”，实际路由也可能切换。因此，应检查**当前去程、回程以及晚高峰表现**，而不是只看套餐名称。 ### 线路测试方法 从本地测试 VPS： ```bash ping VPS_IP mtr -rwzc 100 VPS_IP ``` 如果本地没有 `mtr`，也可先使用： ```bash traceroute VPS_IP ``` Windows 可以使用： ```powershell tracert VPS_IP pathping VPS_IP ``` 测速建议使用自建 `iperf3` 节点： 服务端： ```bash iperf3 -s ``` 客户端： ```bash iperf3 -c SERVER_IP iperf3 -c SERVER_IP -R ``` `-R` 用于测试反向传输。测试时应覆盖： - 工作日上午； - 晚上 20:00～23:00； - 电信、联通、移动中的目标用户网络； - 单线程与多线程； - 上传与下载； - IPv4 与 IPv6。 只测试一次 Speedtest 不能说明线路质量。建站用户更应关注延迟、丢包和稳定性，而不是瞬时峰值速度。 ## 八、2026 年便宜 VPS 候选类型与服务商参考 以下不是无条件推荐，也不表示所有产品都便宜。不同地区、账户、税率和活动会导致价格明显变化，具体套餐必须到官方网站复核。 ### 1\. 国内云厂商轻量服务器 可关注阿里云、腾讯云、华为云等厂商的轻量应用服务器或入门云服务器。 **优点：** - 中国大陆节点访问稳定； - 中文控制台和工单支持较方便； - 实名、备案和安全产品体系较完整； - 常见应用镜像较丰富。 **缺点：** - 低价往往面向新用户或指定套餐； - 续费价格可能与首购价格不同； - 中国大陆节点建站通常需要备案； - 带宽、流量和备案接入条件要逐项确认。 **适用场景：** - 面向中国大陆用户的网站； - 企业展示站、小程序后端； - 对中文客服和合规要求较高的业务。 购买时不要只看首页的“低至”价格，应确认购买时长、地域、带宽、流量包、续费规则和是否仅限首台实例。 ### 2\. Hetzner 等欧洲高性价比云平台 Hetzner 的云主机和独立服务器长期受到开发者关注，欧洲节点通常具有较好的计算和网络性价比；其可售地区、CPU 架构、价格和 IPv4 计费方式可能调整，应查看当前官网。 **优点：** - 欧洲方向性价比较高； - 控制台、API 和云主机功能较成熟； - 适合欧洲网站、开发测试和数据处理。 **缺点：** - 中国大陆方向通常不是专门优化线路； - 账户审核和风控可能较严格； - 税费、IPv4、备份等项目可能影响总价； - 不适合把低延迟回国作为首要需求。 **适用场景：** - 欧洲用户网站； - CI/CD、编译和远程开发； - 对配置要求高、对中国线路要求不高的服务。 ### 3\. OVHcloud OVHcloud 在欧洲和北美拥有较多基础设施，VPS、云主机和独立服务器产品线较完整。 **优点：** - 机房和产品选择较多； - 部分产品强调 DDoS 防护； - 适合欧洲、北美业务。 **缺点：** - 不同产品线的性能和计费方式差异较大； - 中国方向线路不一定理想； - 防护能力、攻击阈值和清洗策略不能只凭宣传判断； - 退款与取消规则需要按地区站点核对。 **适用场景：** - 海外网站和游戏服务； - 需要一定网络防护的公开服务； - 欧洲或北美用户为主的业务。 ### 4\. Vultr、DigitalOcean、Akamai Cloud 这些平台通常提供按小时或按月计费、API、镜像、快照和多个区域，适合开发者快速部署。它们未必是市场上最便宜的选择，但计费和管理通常比小型年付商家清晰。 **优点：** - 部署和删除方便； - 地区选择较多； - API、快照、防火墙等功能较完整； - 适合短期项目，避免一次支付多年费用。 **缺点：** - 同配置价格通常高于促销型年付 VPS； - 出站流量、备份、快照和附加服务可能增加成本； - 不同地区到中国大陆的网络质量差异明显； - 删除实例前必须确认附加资源是否仍在计费。 **适用场景：** - 开发测试； - 临时项目； - 海外 SaaS 和 API； - 需要快速扩容或自动化部署的用户。 ### 5\. RackNerd、CloudCone 等促销型年付 VPS 这类厂商常见于黑色星期五、周年活动或社区促销，年付价格可能较低。套餐、库存和活动入口变化频繁，不能把历史优惠当作当前价格。 **优点：** - 入门成本低； - 常见美国机房； - 适合探针、测试节点和非关键服务。 **缺点：** - 活动套餐可能不支持退款或迁移； - CPU、磁盘和网络在高峰期可能波动； - 续费价格是否保持不变必须单独确认； - 工单响应和服务能力不能与大型云平台直接比较。 **适用场景：** - 学习 Linux； - 低负载个人服务； - 可随时迁移的备用节点。 不建议将唯一数据库、重要邮件系统或没有备份的生产网站放在超低价年付 VPS 上。 ### 6\. 搬瓦工等中国线路取向产品 部分厂商会提供面向中国大陆优化的香港、日本或美国线路，其中可能涉及 CN2 GIA、CMI 等网络。此类产品通常比普通国际线路贵，热门套餐还可能缺货。 **优点：** - 部分线路对中国大陆延迟和晚高峰体验较好； - 适合需要跨境访问的个人网站或开发环境。 **缺点：** - 单位配置价格较高； - 流量可能少于普通线路套餐； - 线路可能调整，产品名称不能替代实际路由； - 库存、迁移政策和退款条件需要确认。 **适用场景：** - 预算允许且重视中国大陆访问质量； - 用户分布明确，经过测试确认线路有效； - 能接受流量限制的轻量服务。 ## 九、按使用场景给出实际选择建议 ### 面向中国大陆用户建站 优先顺序可以是： 1. 中国大陆节点，完成实名和备案； 2. 经测试稳定的香港、日本或新加坡节点； 3. 中国方向优化的美国西海岸节点； 4. 普通国际线路。 如果只是为了免备案选择香港节点，应先测试目标地区三网表现。香港机房物理距离近，但国际出口拥塞时，体验未必比洛杉矶优化线路好。 ### 面向海外用户建站 按照用户所在地选择就近机房： - 欧洲用户：德国、芬兰、荷兰、法国等； - 北美用户：美国东部或西部； - 东南亚用户：新加坡、日本； - 全球用户：源站加 CDN，而不是要求一台 VPS 覆盖全球。 选择 CDN 时，要确认动态请求、WebSocket、大文件、回源流量和中国大陆加速是否在其实际服务范围内。 ### 学习 Linux 或运行个人项目 可选择 1～2GB 内存的月付云主机，或者信誉较稳定的低价年付 VPS。月付略贵，但方便测试和取消；年付更便宜，但退款和闲置风险更高。 ### WordPress 和小型数据库 建议至少： - 2 vCPU； - 2GB 内存，推荐 4GB； - 30GB 以上 SSD/NVMe； - 定期异地备份； - 可接受的 4K 随机读写； - 明确的月流量额度。 数据库性能差时，增加 CPU 核数未必有效。磁盘延迟、内存缓存和 PHP 配置通常更值得优先优化。 ### 远程开发和 Docker 优先选择： - 2～4 vCPU； - 4GB 以上内存； - 40GB 以上磁盘； - 可创建快照； - 支持自定义镜像或救援模式； - 端口和防火墙规则清晰。 如果需要频繁拉取容器镜像，还应考虑国际网络质量和磁盘空间。Docker 日志未设置轮转时，很容易占满系统盘。 ## 十、便宜 VPS 最常见的十个坑 ### 1\. 首购便宜，续费翻倍 必须分别确认： - 首期价格； - 自动续费价格； - 手动续费价格； - 优惠是否只限首年； - 续费是否保留原配置和原线路。 不要根据第三方测评中的历史续费规则做决定，厂商条款可能已经改变。 ### 2\. 年付套餐不退款 很多特价、年付、加密货币支付或已消耗资源的订单不支持退款。即使官网存在退款政策，也可能排除： - 特价套餐； - 域名、许可证和附加 IP； - 流量已经大量使用的实例； - 违反使用政策的账户； - 加密货币或特定支付渠道。 下单前保存产品页面、订单信息和退款条款截图。不要通过拒付代替正常退款流程，否则可能导致账户及其他实例被一并封禁。 ### 3\. 宣称独立 IPv4，实际是 NAT VPS NAT VPS 可能只分配共享 IPv4 和少量端口。购买前确认： - 是否有独立公网 IPv4； - 可用端口数量； - 端口能否自定义； - 是否提供原生 IPv6； - ICMP、UDP 和常用协议是否受限。 需要开放标准 80/443、运行邮件或某些游戏服务时，NAT VPS 往往不合适。 ### 4\. 无限流量其实有公平使用限制 “Unlimited”通常不等于可以持续跑满端口。服务商可能根据公平使用政策进行限速、暂停或要求升级。必须查看可接受使用政策，而不是只看产品标题。 ### 5\. 线路名称与实际路由不符 任何 CN2 GIA、CMI、精品网或三网优化标签都需要通过当前路由验证。还要区分： - 去程优化、回程普通； - 电信优化、移动绕路； - 白天正常、晚高峰拥塞； - IPv4 优化、IPv6 走普通线路。 ### 6\. CPU 核数多，但持续性能差 促销 VPS 的 CPU 可能允许短时突发，却不允许长时间满载。建站影响较小，转码、编译和游戏服务器影响明显。 ### 7\. 磁盘空间不能扩容 部分年付 VPS 更换套餐或扩容不方便。Docker、数据库和日志增长速度常被低估，建议预留至少 30% 空间。 ### 8\. 没有真正的备份 快照不一定等同于备份。快照可能与实例位于同一平台，账户被封、区域故障或误删资源时可能一起丢失。重要数据至少保留： - VPS 本地副本； - 不同服务商的异地副本； - 定期验证可恢复性的备份。 ### 9\. 25 端口被封，无法直接发邮件 许多云平台默认限制 SMTP 25 端口，以降低滥用风险。即使可以申请解封，新 IP 的邮件信誉也可能很差。生产邮件建议使用合规的第三方邮件投递服务，并提前核实端口政策。 ### 10\. IP 地址有历史问题 低价 VPS 的 IPv4 可能曾被滥用，导致： - 搜索引擎验证频繁； - 邮件进入垃圾箱； - 流媒体或网站拒绝访问； - IP 位置信息错误； - IP 出现在黑名单中。 购买后应尽快检查 IP 信誉和地理位置。如果业务依赖特定地区识别，必须以目标平台的实际识别结果为准，不能只看普通 IP 查询网站。 ## 十一、收货后的检查清单 拿到 VPS 后，建议在退款窗口内完成以下检查；如果套餐明确不退款，也应尽早测试，以便决定是否迁移业务。 ### 系统与配置 ```bash uname -a lscpu free -h df -hT lsblk systemd-detect-virt ``` 确认 CPU 核数、内存、磁盘容量和虚拟化类型与订单一致。 ### 网络 ```bash ip addr ip route ping -c 20 1.1.1.1 mtr -rwzc 100 1.1.1.1 ``` 再从目标用户所在地测试 VPS IP，至少覆盖一个晚高峰时段。 ### 时间与 DNS ```bash timedatectl resolvectl status ``` 确保系统时间同步正常，否则 HTTPS、软件源和日志可能出现异常。 ### 基础安全 1. 更新系统补丁； 2. 创建普通用户； 3. 使用 SSH 密钥； 4. 禁止不必要的密码登录； 5. 配置防火墙； 6. 关闭未使用的服务； 7. 设置日志轮转； 8. 配置异地备份； 9. 不直接运行来源不明的一键脚本。 更改 SSH 端口只能减少日志噪声，不能代替密钥认证、补丁更新和访问控制。 ## 十二、如何在两个便宜 VPS 之间做决定 可以使用一个简单的权重表： | 项目 | 建站权重 | 开发测试权重 | 中国大陆访问权重 | | -------- | ---- | ------ | -------- | | CPU 持续性能 | 15% | 25% | 10% | | 内存与磁盘 | 20% | 25% | 10% | | 网络稳定性 | 25% | 15% | 35% | | 流量与带宽 | 10% | 10% | 15% | | 备份与控制台 | 15% | 15% | 10% | | 续费与退款 | 15% | 10% | 20% | 不要用跑分直接代替业务测试。WordPress 用户可以测试后台响应和数据库查询；开发用户可以测试构建时间；跨境业务应测试真实 API 的连接成功率与 P95 延迟。 ## 十三、最终购买建议 如果预算很低，可以遵循以下原则： - **重要业务优先月付**，确认稳定后再考虑长期付款； - **普通海外业务优先主流云平台或稳定的欧洲厂商**，不要只追求最低年付价； - **面向中国大陆用户优先看线路实测**，机房名称和营销标签只能作为参考； - **低负载学习用途可以选择年付促销 VPS**，但必须接受不退款和性能波动； - **数据库、邮件和核心生产业务不要只部署一台低价 VPS**； - **首购前核对续费价、税费、IPv4、备份和超额流量费用**； - **任何无法确认的线路和优惠信息，都以购买当天的官网页面及服务条款为准**。 真正值得购买的便宜 VPS，应该是满足需求后的低成本方案，而不是配置表上最便宜的那一台。与其购买三台无法稳定使用的年付机器，不如把预算集中到一台 CPU、磁盘和网络都经过验证的 VPS，并为重要数据配置独立备份。 ### Cursor + Claude 3.5 编程实战：不懂代码的普通人如何一天写出一个 Web App URL: https://isoziyuan.com/p/100100/ Last updated: 2026-08-27T04:38:37.000Z > \*\*先说明模型可用性：\*\*截至你实际操作时，Cursor 中可选择的模型会随版本、地区、账户权限和服务策略变化。本文所说的 **Claude 3.5**，主要指 Claude 3.5 Sonnet 这类适合编程的模型；如果 Cursor 的模型列表中已经没有它，请直接选择当时可用的 Claude 编程模型。操作方法和提示词仍然适用。本文不承诺特定模型免费，也不引用可能过期的价格或额度。 ## 为什么普通人用 AI 编程，仍然经常做不出产品 很多零基础用户第一次打开 Cursor，会直接输入： > 帮我做一个网站，要高级、好看、功能完整。 随后通常会遇到几个问题： 1. **需求太模糊**：AI 不知道页面给谁用、解决什么问题。 2. **一次生成太多代码**：出错后不知道改哪一个文件。 3. **只看页面，不测功能**：刷新后数据消失、按钮无效、手机端错位。 4. **频繁要求“全部重写”**：刚修好的功能又被覆盖。 5. **一开始就接数据库、支付和登录**：复杂度突然失控。 6. **把 AI 当成全自动外包**：自己不确认每一步，最后无法维护。 真正适合一天完成的，不是复杂 SaaS，而是一个范围明确的 **MVP（最小可用产品）**。 本文将用 Cursor + Claude 3.5 完成一个可以实际运行的 Web App： - 添加任务 - 标记任务完成 - 删除任务 - 按状态筛选 - 自动保存到浏览器 - 25 分钟专注计时 - 适配手机和电脑 - 不需要服务器、数据库或第三方接口 - 可以部署到 GitHub Pages 项目名为：**Focus Board 番茄任务板**。 --- ## 一天能做到什么，不能做到什么 ### 适合一天完成 - 个人工具 - 单页落地页 - 待办清单 - 计算器 - 习惯打卡工具 - 内容整理工具 - 调用一个已有 API 的简单应用 - 不登录、不支付的静态 Web App ### 不适合一天承诺完成 - 真实支付系统 - 多用户权限 - 即时聊天 - 复杂后台管理系统 - 医疗、金融等高风险业务 - 大规模数据同步 - 完整商业级 SaaS 本文中的“一天写出一个 Web App”，指完成一个**可以打开、可以操作、可以保存本地数据、可以部署分享的 MVP**，不等于一天完成成熟商业产品。 --- ## 准备工作 ### 1\. 安装必要工具 你需要： - Cursor 编辑器 - 一个可用的 Cursor 账户 - Chrome、Edge 或 Firefox 等现代浏览器 - Git - GitHub 账户，用于部署 - 可选：Python，用于启动本地静态服务器 Cursor、模型权限和使用限制可能变化，请以 Cursor 官方网站及应用内显示为准。 ### 2\. 在 Cursor 中选择模型 打开 Cursor 的聊天或 Agent 面板，在模型选择器中寻找 Claude 3.5 Sonnet。 如果没有这个选项： - 不要寻找所谓“隐藏开启方法” - 不要使用来历不明的中转接口 - 直接选择 Cursor 当前提供的 Claude 模型 - 保留本文的任务拆分方法和提示词即可 Cursor 不同版本可能把功能命名为 Agent、Chat、Edit 等，界面位置也可能调整。核心原则是： - **聊天模式**：讨论方案、解释错误 - **编辑或 Agent 模式**：创建和修改项目文件 - **终端**：运行项目和执行 Git 命令 ### 3\. 创建项目文件夹 新建一个空文件夹： ```text focus-board ``` 使用 Cursor 打开这个文件夹。 然后在 Cursor 的终端中执行： ```bash git init ``` 这一步不是为了炫技，而是为了让你在 AI 改坏代码后能够回退。 --- ## 项目结构 最终只需要三个文件： ```text focus-board/ ├── index.html ├── styles.css └── app.js ``` 我们不使用 React、Vue、数据库或构建工具。 原因很简单：对零基础用户而言，原生 HTML、CSS、JavaScript 更容易运行，也更容易排查问题。 --- ## 第一步：先让 Claude 写需求，不要立即写代码 把下面的提示词发给 Cursor 中的 Claude 3.5： ```text 你是资深产品经理和前端工程师。 我要在一天内完成一个名为 Focus Board 的单页 Web App，目标用户是需要管理任务和专注时间的普通人。 核心功能： 1. 添加任务 2. 标记任务完成 3. 删除任务 4. 筛选全部、进行中、已完成任务 5. 使用 localStorage 保存任务，刷新页面后不能丢失 6. 提供 25 分钟专注计时器 7. 适配手机和桌面端 8. 不使用后端、数据库、第三方 API 和前端框架 请先不要写代码。 请输出： - 一句话产品定位 - 用户操作流程 - 功能清单 - 不做的功能 - 验收标准 - 项目文件结构 如果需求存在不合理之处，请直接指出。 ``` ### 为什么要先做这一步 AI编程最重要的不是“让 AI 多写代码”，而是让 AI 明确边界。 你需要重点检查它给出的验收标准，至少应包括： - 输入空内容时不能添加任务 - 新任务能够立即显示 - 刷新页面后任务仍存在 - 完成状态能够切换 - 删除按钮有效 - 三种筛选状态正确 - 计时器能够开始、暂停和重置 - 页面在窄屏下不横向溢出 如果 Claude 自行增加了登录、云同步、AI 分析、排行榜等功能，要求它删除。 --- ## 第二步：让 Cursor 创建基础文件 继续发送： ```text 请根据刚才确认的需求创建以下三个文件： - index.html - styles.css - app.js 技术要求： 1. 只使用原生 HTML、CSS 和 JavaScript 2. 不引用外部 CDN 3. 不使用内联 JavaScript 4. 所有按钮必须有明确的 type 属性 5. 输入框必须有关联的 label 6. 动态任务内容必须使用 textContent 渲染，不能直接拼接 innerHTML 7. localStorage 读取失败时要有容错 8. 代码中添加适量中文注释 9. 先完成最小可用版本，不增加额外功能 请逐个文件修改，并在完成后说明每个文件的作用。 ``` 如果 Cursor 提示是否应用修改，先查看文件范围。确认它只修改当前项目中的三个文件，再接受修改。 为了让教程可以直接执行，下面给出一套完整代码。你既可以手动复制，也可以用它对照 Cursor 的输出。 --- ## 第三步：编写页面结构 在 `index.html` 中放入： ```htmlFOCUS BOARD
添加任务，开始 25 分钟专注，并在当前浏览器中保存进度。
TASKS
0 个未完成
还没有任务，先添加一件今天最重要的事。
FOCUS TIMER
一次只处理一件事。
准备开始