From c7d97d5018fdb8d9cd6407db19238c96516bbb00 Mon Sep 17 00:00:00 2001 From: linshen <32978552+linshenkx@users.noreply.github.com> Date: Wed, 27 May 2026 23:17:46 +0800 Subject: [PATCH] docs: refine deployment guidance - Align Cloudflare Workers setup across README and user docs - Clarify build command cleanup and deployment context notes - Keep frontend API key exposure warnings concise across providers --- README.md | 14 ++-- README.zh-CN.md | 14 ++-- docs/user/README.md | 4 +- docs/user/deployment/cloudflare-pages.md | 92 +++++++++++++-------- docs/user/deployment/cloudflare-pages_en.md | 92 +++++++++++++-------- docs/user/deployment/vercel.md | 3 +- docs/user/deployment/vercel_en.md | 3 +- mkdocs/docs/en/deployment/web.md | 71 +++++++++------- mkdocs/docs/zh/deployment/web.md | 71 +++++++++------- wrangler.jsonc | 11 +++ 10 files changed, 225 insertions(+), 150 deletions(-) create mode 100644 wrangler.jsonc diff --git a/README.md b/README.md index 004c8283..20c93d43 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ [Website](https://always200.com) | [Online Optimizer](https://prompt.always200.com) | [Prompt Garden](https://garden.always200.com) | [Docs](https://docs.always200.com) | [Quick Start](#quick-start) | [Chrome Extension](https://chromewebstore.google.com/detail/prompt-optimizer/cakkkhboolfnadechdlgdcnjammejlna) | [💖 Support](https://ko-fi.com/linshenkx) -[Development Docs](docs/developer/development.md) | [Vercel Deployment Guide](docs/user/deployment/vercel_en.md) | [Cloudflare Pages Deployment Guide](docs/user/deployment/cloudflare-pages_en.md) | [MCP Deployment Guide](docs/user/mcp-server_en.md) | [DeepWiki Docs](https://deepwiki.com/linshenkx/prompt-optimizer) | [ZRead Docs](https://zread.ai/linshenkx/prompt-optimizer) +[Development Docs](docs/developer/development.md) | [Vercel Deployment Guide](docs/user/deployment/vercel_en.md) | [Cloudflare Deployment Guide](docs/user/deployment/cloudflare-pages_en.md) | [MCP Deployment Guide](docs/user/mcp-server_en.md) | [DeepWiki Docs](https://deepwiki.com/linshenkx/prompt-optimizer) | [ZRead Docs](https://zread.ai/linshenkx/prompt-optimizer) @@ -103,15 +103,17 @@ Method 2: Fork the project and import to Vercel (Recommended): - This allows tracking of source project updates for easy syncing of new features and fixes - Configure environment variables: - `ACCESS_PASSWORD`: Set access password to enable access restriction - - `VITE_OPENAI_API_KEY` etc.: Configure API keys for various AI service providers + - `VITE_OPENAI_API_KEY` etc.: Optional private-deployment model settings. Do not preconfigure API keys on public frontend deployments because `VITE_*` values are exposed in browser assets. For more detailed deployment steps and important notes, please check: - [Vercel Deployment Guide](docs/user/deployment/vercel_en.md) -- [Cloudflare Pages Deployment Guide](docs/user/deployment/cloudflare-pages_en.md) +- [Cloudflare Deployment Guide](docs/user/deployment/cloudflare-pages_en.md) -#### Cloudflare Pages Deployment +#### Cloudflare Deployment -Fork the project and import your fork into Cloudflare Pages. Use the repository root, set the build output directory to `packages/web/dist`, and sync your fork later to trigger automatic redeploys. +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linshenkx/prompt-optimizer) + +Use the Deploy to Cloudflare button for the quickest public-repository setup. It creates a repository under your GitHub/GitLab account and deploys with Workers Builds. For private repositories or stricter repository-access control, import your own repository manually; keep the default deploy commands and clear the build command if Cloudflare auto-fills `pnpm run build`, because `wrangler.jsonc` builds the Web frontend and publishes `packages/web/dist` as static assets. For access control and analytics on Cloudflare, configure Cloudflare Access and Cloudflare Web Analytics in the Cloudflare dashboard. No frontend dependency or application-code change is required. @@ -364,7 +366,7 @@ For detailed project status, see [Project Status Document](docs/project/project- - [Project Status](docs/project/project-status.md) - Current progress and plans - [Product Requirements](docs/project/prd.md) - Product requirements document - [Vercel Deployment Guide](docs/user/deployment/vercel_en.md) - Detailed instructions for Vercel deployment -- [Cloudflare Pages Deployment Guide](docs/user/deployment/cloudflare-pages_en.md) - Web frontend deployment on Cloudflare Pages +- [Cloudflare Deployment Guide](docs/user/deployment/cloudflare-pages_en.md) - Web frontend deployment on Cloudflare Workers / Pages ## Star History diff --git a/README.zh-CN.md b/README.zh-CN.md index 36762157..6993dc09 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -16,7 +16,7 @@ [官网](https://always200.com) | [在线优化器](https://prompt.always200.com) | [提示词库](https://garden.always200.com) | [文档站](https://docs.always200.com) | [快速开始](#快速开始) | [Chrome插件](https://chromewebstore.google.com/detail/prompt-optimizer/cakkkhboolfnadechdlgdcnjammejlna) | [💖赞助支持](images/other/sponsor_wx.jpg) -[开发文档](docs/developer/development.md) | [Vercel部署指南](docs/user/deployment/vercel.md) | [Cloudflare Pages部署指南](docs/user/deployment/cloudflare-pages.md) | [MCP部署使用说明](docs/user/mcp-server.md) | [DeepWiki文档](https://deepwiki.com/linshenkx/prompt-optimizer) | [ZRead文档](https://zread.ai/linshenkx/prompt-optimizer) +[开发文档](docs/developer/development.md) | [Vercel部署指南](docs/user/deployment/vercel.md) | [Cloudflare部署指南](docs/user/deployment/cloudflare-pages.md) | [MCP部署使用说明](docs/user/mcp-server.md) | [DeepWiki文档](https://deepwiki.com/linshenkx/prompt-optimizer) | [ZRead文档](https://zread.ai/linshenkx/prompt-optimizer) @@ -103,15 +103,17 @@ Prompt Optimizer是一个强大的AI提示词优化工具，帮助你编写更 - 可跟踪源项目更新，便于同步最新功能和修复 - 配置环境变量： - `ACCESS_PASSWORD`：设置访问密码，启用访问限制 - - `VITE_OPENAI_API_KEY`等：配置各AI服务商的API密钥 + - `VITE_OPENAI_API_KEY` 等：仅用于私有部署的可选模型配置。公开前端部署不要预置 API 密钥，因为 `VITE_*` 值会暴露在浏览器资源中。 更多详细的部署步骤和注意事项，请查看： - [Vercel部署指南](docs/user/deployment/vercel.md) -- [Cloudflare Pages部署指南](docs/user/deployment/cloudflare-pages.md) +- [Cloudflare部署指南](docs/user/deployment/cloudflare-pages.md) -#### Cloudflare Pages部署 +#### Cloudflare 部署 -Fork 项目后在 Cloudflare Pages 中导入自己的 fork。保持仓库根目录，构建产物目录设置为 `packages/web/dist`，后续同步 fork 后会自动重新部署。 +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linshenkx/prompt-optimizer) + +公开仓库用户优先使用 Deploy to Cloudflare 按钮，它会在你的 GitHub/GitLab 账号下创建仓库并用 Workers Builds 部署。需要私有仓库或更严格的仓库权限控制时，再手动导入自己的仓库；保持默认部署命令，如果 Cloudflare 自动填入 `pnpm run build`，请清空构建命令，因为 `wrangler.jsonc` 会构建 Web 前端并把 `packages/web/dist` 发布为静态资源。 Cloudflare 上的访问控制和访问分析建议分别使用 Cloudflare Access 和 Cloudflare Web Analytics，在 Cloudflare 控制台配置即可，不需要安装前端依赖或修改应用代码。 @@ -358,7 +360,7 @@ pnpm dev:fresh # 完整重置并重新启动开发环境 - [项目状态](docs/project/project-status.md) - 当前进度和计划 - [产品需求](docs/project/prd.md) - 产品需求文档 - [Vercel部署指南](docs/user/deployment/vercel.md) - Vercel部署详细说明 -- [Cloudflare Pages部署指南](docs/user/deployment/cloudflare-pages.md) - 在 Cloudflare Pages 上部署 Web 前端 +- [Cloudflare部署指南](docs/user/deployment/cloudflare-pages.md) - 在 Cloudflare Workers / Pages 上部署 Web 前端 ## Star History diff --git a/docs/user/README.md b/docs/user/README.md index e61589bb..eb15e7c3 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -25,8 +25,8 @@ ### 自部署 - [Vercel部署指南（中文）](./deployment/vercel.md) - 在Vercel上部署Web版 - [Vercel部署指南（英文）](./deployment/vercel_en.md) - Vercel deployment guide (English) -- [Cloudflare Pages部署指南（中文）](./deployment/cloudflare-pages.md) - 在 Cloudflare Pages 上部署 Web 前端 -- [Cloudflare Pages Deployment Guide (English)](./deployment/cloudflare-pages_en.md) - Deploy the Web frontend on Cloudflare Pages +- [Cloudflare部署指南（中文）](./deployment/cloudflare-pages.md) - 在 Cloudflare Workers / Pages 上部署 Web 前端 +- [Cloudflare Deployment Guide (English)](./deployment/cloudflare-pages_en.md) - Deploy the Web frontend on Cloudflare Workers / Pages ## ❓ 常见问题 diff --git a/docs/user/deployment/cloudflare-pages.md b/docs/user/deployment/cloudflare-pages.md index b19ce3f8..3da7deb2 100644 --- a/docs/user/deployment/cloudflare-pages.md +++ b/docs/user/deployment/cloudflare-pages.md @@ -1,85 +1,103 @@ -## Cloudflare Pages 部署说明 +## Cloudflare 部署说明 -Cloudflare Pages 适合部署 Prompt Optimizer 的 **Web 前端**。它提供静态站点托管和 Git 自动部署；站点访问控制、访问分析等能力由 Cloudflare 控制台配置。 +Cloudflare 适合部署 Prompt Optimizer 的 **Web 前端**。当前 Cloudflare Dashboard 可能会把 GitHub 仓库导入到 **Workers Static Assets** 流程，而不是旧版 **Pages** 表单。两种方式都能部署静态前端，但如果你的界面出现“创建 Worker”“部署命令 `npx wrangler deploy`”，请优先按下面的 Workers 流程配置。 -### 推荐方式：Fork 后导入 Cloudflare Pages +### 推荐方式：一键部署 -这种方式和推荐的 Vercel 部署方式一样：部署绑定到你自己的 fork，后续同步上游更新后会自动重新部署。 +公开仓库用户可以优先使用 Cloudflare 官方的一键部署按钮： + +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linshenkx/prompt-optimizer) + +这个流程会把源仓库克隆到你的 GitHub/GitLab 账号下，并使用 Workers Builds 创建和部署 Worker。仓库根目录已经包含 `wrangler.jsonc`，用于告诉 Cloudflare Workers 如何构建 Web 前端、发布 `packages/web/dist` 静态资源，并为单页应用启用 `index.html` 回退。 + +需要注意： + +- Deploy to Cloudflare 按钮要求源仓库是公开的 GitHub/GitLab 仓库。 +- 如果你想使用私有仓库，或想手动限制 Cloudflare GitHub App 只访问指定仓库，请使用下面的手动导入方式。 + +### 备选方式：手动导入仓库 + +手动导入适合私有仓库、组织仓库、需要精细控制 GitHub App 权限，或一键部署按钮失败的场景。 1. **Fork 项目到自己的 GitHub** - 访问 [prompt-optimizer 项目](https://github.com/linshenkx/prompt-optimizer) - 点击右上角的 "Fork" - 完成后，你会在自己的 GitHub 账号下拥有一份仓库副本 -2. **在 Cloudflare Pages 中导入仓库** +2. **在 Cloudflare 中导入仓库** - 登录 [Cloudflare Dashboard](https://dash.cloudflare.com/) - 进入 **Workers & Pages** - - 选择 **Create application** -> **Pages** -> **Connect to Git** + - 选择通过 GitHub/Git 仓库创建应用 - 选择你 fork 后的 `prompt-optimizer` 仓库 -3. **配置构建参数** +3. **确认 Worker 设置** - 建议保持仓库根目录作为项目根目录，不要把根目录改成 `packages/web`。 + 如果界面显示“创建 Worker”，大多数配置可以保持默认。Worker 名称需要和根目录 `wrangler.jsonc` 中的 `name` 保持一致。 | 配置项 | 推荐值 | | --- | --- | - | Framework preset | `None` 或留空 | - | Root directory | `/` 或留空 | - | Build command | `pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build` | - | Build output directory | `packages/web/dist` | + | Worker name | 如果自动填入 `prompt-optimizer`，保持不变；否则改成 `prompt-optimizer` | + | Root directory / Path | 保持默认，通常是 `/` 或留空 | + | Build command | 清空；如果自动填入 `pnpm run build`，请删除。`wrangler.jsonc` 已配置构建命令 | + | Deploy command | 保持默认 `npx wrangler deploy` | + | Non-production branch deploy command | 保持默认 `npx wrangler versions upload` | -4. **配置环境变量** +4. **环境变量** - 在 Cloudflare Pages 项目的 **Settings** -> **Environment variables** 中添加： + 通常不需要手动配置构建环境变量。Cloudflare 会根据仓库里的 `packageManager` 和 `engines` 检测 `pnpm` 和 Node.js 版本。 + + 如果 Cloudflare 检测到的版本不正确，再在项目的构建环境变量中添加： ```bash NODE_VERSION=22 PNPM_VERSION=10.6.1 ``` - 如果你希望预置模型 API Key，也可以添加常用的 `VITE_*` 环境变量： + 不要在公开 Cloudflare 站点中预置模型 API Key。所有 `VITE_*` 变量都会进入前端构建产物，访问者可以在浏览器下载到这些值。公开站点应让用户在应用界面的模型管理中自行填写自己的 API Key。 - ```bash - VITE_OPENAI_API_KEY=... - VITE_GEMINI_API_KEY=... - VITE_DEEPSEEK_API_KEY=... - VITE_GROK_API_KEY=... - VITE_SILICONFLOW_API_KEY=... - VITE_ZHIPU_API_KEY=... - ``` - - 也可以不在部署平台配置 API Key，让用户在应用界面的模型管理中自行填写。这样更适合公开站点。 + 只有在受控的私有部署中，才考虑预置 `VITE_*` 模型配置；同时应配合 Cloudflare Access，并使用可轮换、权限受限、费用受控的密钥。 5. **部署** - 保存配置并开始部署 - - 部署成功后，Cloudflare Pages 会提供一个 `*.pages.dev` 域名 - - 后续你的 fork 有新 commit 时，Cloudflare Pages 会自动重新构建并部署 + - 部署成功后，Cloudflare Workers 会提供一个 `*.workers.dev` 域名；你也可以后续绑定自定义域名 + - 后续你的 fork 有新 commit 时，Cloudflare 会自动重新构建并部署 6. **同步上游更新** - 在 GitHub 打开你 fork 的仓库 - 当页面提示落后于 `linshenkx/prompt-optimizer` 时，点击 **Sync fork** - - 同步产生新 commit 后，Cloudflare Pages 会自动重新部署 + - 同步产生新 commit 后，Cloudflare 会自动重新部署 + +### 备选方式：旧版 Cloudflare Pages 表单 + +如果你的 Cloudflare Dashboard 仍然显示 **Create application** -> **Pages** -> **Connect to Git**，也可以继续用 Pages 表单： + +| 配置项 | 推荐值 | +| --- | --- | +| Framework preset | `None` 或留空 | +| Root directory | `/` 或留空 | +| Build command | `pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build` | +| Build output directory | `packages/web/dist` | ### 可选：访问控制 -Cloudflare Pages 部署不使用 Vercel 的 `ACCESS_PASSWORD`、`middleware.js` 或 `api/auth.js`。如果你想限制访问，推荐使用 **Cloudflare Access**： +Cloudflare 部署不使用 Vercel 的 `ACCESS_PASSWORD`、`middleware.js` 或 `api/auth.js`。如果你想限制访问，推荐使用 **Cloudflare Access**： 1. 进入 Cloudflare Zero Trust 2. 创建一个 Self-hosted application -3. 绑定你的 Pages 域名 +3. 绑定你的 Workers 或 Pages 域名 4. 配置允许访问的邮箱、域名、身份提供商或其他策略 这样访问请求会先经过 Cloudflare Access，再进入静态站点，不需要修改前端代码。 ### 可选：访问分析 -Cloudflare Pages 可以在项目的 **Metrics** -> **Web Analytics** 中启用 Web Analytics。Cloudflare 会在后续部署中自动注入统计脚本，不需要安装类似 `@vercel/analytics` 的前端依赖。 +Cloudflare Web Analytics 可以在 Cloudflare 控制台启用，不需要安装类似 `@vercel/analytics` 的前端依赖。 需要注意：Prompt Optimizer 当前使用 hash 路由，因此 Cloudflare Web Analytics 可以统计站点访问和性能数据，但不会自动把 `/#/xxx` 这类 hash 内页面切换当作独立页面浏览。 ### 和 Vercel 部署的区别 -| 能力 | Vercel | Cloudflare Pages | +| 能力 | Vercel | Cloudflare Workers / Pages | | --- | --- | --- | | Web 前端部署 | 支持 | 支持 | | Fork 后自动部署 | 支持 | 支持 | @@ -91,12 +109,14 @@ Cloudflare Pages 可以在项目的 **Metrics** -> **Web Analytics** 中启用 W #### 修改环境变量后没有生效 -Cloudflare Pages 的构建环境变量需要重新部署后才会进入前端构建产物。保存环境变量后，请在 **Deployments** 中重新部署一次。 +Cloudflare 的构建环境变量需要重新部署后才会进入前端构建产物。保存环境变量后，请在 **Deployments** 中重新部署一次。 -#### 为什么没有一键部署按钮 +#### 为什么界面显示的是 Worker，不是 Pages -Cloudflare 官方的 "Deploy to Cloudflare" 按钮主要面向 Workers 应用，不适合当前这种 Cloudflare Pages Git 集成部署。为了后续更新更可靠，推荐 Fork 后导入 Cloudflare Pages。 +Cloudflare 控制台现在可能会把 GitHub 静态站点导入到 Workers Static Assets 流程。这个项目是纯前端静态站点，使用 Workers 流程时由 `wrangler.jsonc` 负责构建命令和 `packages/web/dist` 静态资源目录，和 Pages 表单中的构建命令、构建产物目录作用相同。 + +如果部署日志出现 `The Wrangler application detection logic has been run in the root of a workspace`，说明 Wrangler 没有读到项目根目录的 `wrangler.jsonc`，于是尝试在 monorepo 根目录自动识别应用。请确认当前部署的提交已经包含 `wrangler.jsonc`；如果仍然报错，再把部署命令改成 `npx wrangler deploy --config wrangler.jsonc`，把非生产分支部署命令改成 `npx wrangler versions upload --config wrangler.jsonc`。 #### 连接模型 API 失败怎么办 -Cloudflare Pages 部署的是纯前端页面，浏览器仍然会直接请求模型服务。如果模型服务不允许浏览器跨域访问，Web 版会失败。此时建议使用桌面版，或配置你自己的 API 中转服务。 +Cloudflare 部署的是纯前端页面，浏览器仍然会直接请求模型服务。如果模型服务不允许浏览器跨域访问，Web 版会失败。此时建议使用桌面版，或配置你自己的 API 中转服务。 diff --git a/docs/user/deployment/cloudflare-pages_en.md b/docs/user/deployment/cloudflare-pages_en.md index 49b1c7cc..6ea4b07e 100644 --- a/docs/user/deployment/cloudflare-pages_en.md +++ b/docs/user/deployment/cloudflare-pages_en.md @@ -1,85 +1,103 @@ -## Cloudflare Pages Deployment Guide +## Cloudflare Deployment Guide -Cloudflare Pages is suitable for deploying the Prompt Optimizer **Web frontend**. It provides static hosting and Git-triggered deployments; access control and analytics are configured from the Cloudflare dashboard. +Cloudflare is suitable for deploying the Prompt Optimizer **Web frontend**. The current Cloudflare Dashboard may import GitHub repositories through the **Workers Static Assets** flow instead of the older **Pages** form. Both can deploy the static frontend, but if your screen says "Create Worker" and shows a deploy command like `npx wrangler deploy`, use the Workers settings below. -### Recommended method: Fork and import into Cloudflare Pages +### Recommended method: one-click deploy -This follows the same maintenance model as the recommended Vercel deployment: the deployment is connected to your own fork, and Cloudflare Pages redeploys after you sync upstream changes into that fork. +Public-repository users can start with Cloudflare's official one-click deploy button: + +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linshenkx/prompt-optimizer) + +This flow clones the source repository into your GitHub/GitLab account, then creates and deploys a Worker with Workers Builds. The repository root includes `wrangler.jsonc`, which tells Cloudflare Workers how to build the Web frontend, publish the `packages/web/dist` static assets, and use `index.html` fallback routing for the single-page application. + +Important notes: + +- Deploy to Cloudflare buttons require a public GitHub/GitLab source repository. +- If you want to use a private repository, or restrict the Cloudflare GitHub App to selected repositories manually, use the manual import flow below. + +### Alternative: manually import a repository + +Manual import is useful for private repositories, organization repositories, stricter GitHub App access control, or cases where the one-click button does not fit your setup. 1. **Fork the project to your GitHub account** - Visit the [prompt-optimizer repository](https://github.com/linshenkx/prompt-optimizer) - Click "Fork" in the top right corner - After forking, you will have a copy of the repository under your own GitHub account -2. **Import the repository into Cloudflare Pages** +2. **Import the repository into Cloudflare** - Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com/) - Open **Workers & Pages** - - Select **Create application** -> **Pages** -> **Connect to Git** + - Create an application from your GitHub/Git repository - Choose your forked `prompt-optimizer` repository -3. **Configure build settings** +3. **Review Worker settings** - Keep the repository root as the project root. Do not change the root directory to `packages/web`. + If the screen says "Create Worker", most settings can stay at their defaults. The Worker name must match the `name` field in the root `wrangler.jsonc`. | Setting | Recommended value | | --- | --- | - | Framework preset | `None` or empty | - | Root directory | `/` or empty | - | Build command | `pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build` | - | Build output directory | `packages/web/dist` | + | Worker name | Keep `prompt-optimizer` if it is auto-filled; otherwise change it to `prompt-optimizer` | + | Root directory / Path | Keep the default, usually `/` or empty | + | Build command | Clear it; if Cloudflare auto-fills `pnpm run build`, delete it. `wrangler.jsonc` already configures the build command | + | Deploy command | Keep the default `npx wrangler deploy` | + | Non-production branch deploy command | Keep the default `npx wrangler versions upload` | -4. **Configure environment variables** +4. **Environment variables** - In the Cloudflare Pages project, go to **Settings** -> **Environment variables** and add: + You usually do not need to configure build environment variables manually. Cloudflare detects the `pnpm` and Node.js versions from the repository `packageManager` and `engines` fields. + + If Cloudflare detects the wrong versions, add these build environment variables: ```bash NODE_VERSION=22 PNPM_VERSION=10.6.1 ``` - If you want to preconfigure model API keys, you can also add common `VITE_*` variables: + Do not preconfigure model API keys for a public Cloudflare site. Every `VITE_*` variable is bundled into the frontend build output, so visitors can download those values in the browser. For public sites, leave API keys out of the hosting platform and let users configure their own keys in the application UI. - ```bash - VITE_OPENAI_API_KEY=... - VITE_GEMINI_API_KEY=... - VITE_DEEPSEEK_API_KEY=... - VITE_GROK_API_KEY=... - VITE_SILICONFLOW_API_KEY=... - VITE_ZHIPU_API_KEY=... - ``` - - You can also leave API keys out of the hosting platform and let users configure models in the application UI. This is usually better for public deployments. + Only consider preconfigured `VITE_*` model settings for controlled private deployments. Pair that with Cloudflare Access, and use keys that are rotatable, scoped, and cost-limited. 5. **Deploy** - Save the settings and start the deployment - - After deployment succeeds, Cloudflare Pages provides a `*.pages.dev` domain - - Later, whenever your fork receives new commits, Cloudflare Pages rebuilds and redeploys automatically + - After deployment succeeds, Cloudflare Workers provides a `*.workers.dev` domain; you can bind a custom domain later + - Later, whenever your fork receives new commits, Cloudflare rebuilds and redeploys automatically 6. **Sync upstream updates** - Open your forked repository on GitHub - When GitHub shows that it is behind `linshenkx/prompt-optimizer`, click **Sync fork** - - Once the sync creates new commits in your fork, Cloudflare Pages redeploys automatically + - Once the sync creates new commits in your fork, Cloudflare redeploys automatically + +### Alternative: older Cloudflare Pages form + +If your Cloudflare Dashboard still shows **Create application** -> **Pages** -> **Connect to Git**, you can use the Pages form: + +| Setting | Recommended value | +| --- | --- | +| Framework preset | `None` or empty | +| Root directory | `/` or empty | +| Build command | `pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build` | +| Build output directory | `packages/web/dist` | ### Optional: access control -Cloudflare Pages deployment does not use Vercel's `ACCESS_PASSWORD`, `middleware.js`, or `api/auth.js`. If you want restricted access, use **Cloudflare Access**: +Cloudflare deployment does not use Vercel's `ACCESS_PASSWORD`, `middleware.js`, or `api/auth.js`. If you want restricted access, use **Cloudflare Access**: 1. Open Cloudflare Zero Trust 2. Create a Self-hosted application -3. Bind it to your Pages domain +3. Bind it to your Workers or Pages domain 4. Configure allowed emails, domains, identity providers, or other access policies Requests will pass through Cloudflare Access before reaching the static site, without frontend code changes. ### Optional: analytics -Cloudflare Pages can enable Web Analytics from **Metrics** -> **Web Analytics** in the Pages project. Cloudflare injects the analytics snippet on later deployments, so you do not need a frontend dependency like `@vercel/analytics`. +Cloudflare Web Analytics can be enabled from the Cloudflare dashboard, so you do not need a frontend dependency like `@vercel/analytics`. Note that Prompt Optimizer currently uses hash routing. Cloudflare Web Analytics can track overall site visits and performance, but it will not automatically treat `/#/xxx` hash route changes as separate page views. ### Differences from Vercel deployment -| Capability | Vercel | Cloudflare Pages | +| Capability | Vercel | Cloudflare Workers / Pages | | --- | --- | --- | | Web frontend deployment | Supported | Supported | | Auto deploy after fork commits | Supported | Supported | @@ -91,12 +109,14 @@ Note that Prompt Optimizer currently uses hash routing. Cloudflare Web Analytics #### Environment variable changes did not take effect -Cloudflare Pages build environment variables are included in the frontend build output only after a new deployment. After saving variables, redeploy from **Deployments**. +Cloudflare build environment variables are included in the frontend build output only after a new deployment. After saving variables, redeploy from **Deployments**. -#### Why is there no one-click deploy button? +#### Why does the dashboard show Worker instead of Pages? -Cloudflare's official "Deploy to Cloudflare" button is mainly for Workers applications, not this Cloudflare Pages Git integration flow. For reliable future updates, fork the repository and import the fork into Cloudflare Pages. +The Cloudflare dashboard may now import GitHub static sites through the Workers Static Assets flow. This project is a pure frontend static site. In the Workers flow, `wrangler.jsonc` owns both the build command and the `packages/web/dist` static asset directory, which serve the same roles as the Pages build command and build output directory fields. + +If the deployment log says `The Wrangler application detection logic has been run in the root of a workspace`, Wrangler did not read the root `wrangler.jsonc` and tried to auto-detect an app from the monorepo root. Make sure the deployed commit includes `wrangler.jsonc`. If it still fails, set the deploy command to `npx wrangler deploy --config wrangler.jsonc`, and set the non-production branch deploy command to `npx wrangler versions upload --config wrangler.jsonc`. #### What if model API connections fail? -Cloudflare Pages deploys a pure frontend page. The browser still calls model services directly. If a model provider does not allow browser CORS requests, the Web version will fail. Use the desktop app or configure your own API relay service in that case. +Cloudflare deploys a pure frontend page. The browser still calls model services directly. If a model provider does not allow browser CORS requests, the Web version will fail. Use the desktop app or configure your own API relay service in that case. diff --git a/docs/user/deployment/vercel.md b/docs/user/deployment/vercel.md index 8f3ed603..77c8cb8d 100644 --- a/docs/user/deployment/vercel.md +++ b/docs/user/deployment/vercel.md @@ -42,7 +42,8 @@ 4. **配置环境变量（可选）** - 部署完成后，进入项目设置 - 点击"Environment Variables" - - 添加需要的API密钥（例如`VITE_OPENAI_API_KEY`） + - 不要在公开 Vercel 站点中预置模型 API Key。`VITE_*` 变量会进入前端构建产物，访问者可以在浏览器下载到这些值。公开站点应让用户在应用界面的模型管理中自行填写自己的 API Key。 + - 只有在受控的私有部署中，才考虑预置 `VITE_*` 模型配置；同时应使用可轮换、权限受限、费用受控的密钥。 - 如需添加访问限制功能： - 添加名为`ACCESS_PASSWORD`的环境变量 - 设置一个安全的密码作为其值 diff --git a/docs/user/deployment/vercel_en.md b/docs/user/deployment/vercel_en.md index 9cee4b80..203b3526 100644 --- a/docs/user/deployment/vercel_en.md +++ b/docs/user/deployment/vercel_en.md @@ -42,7 +42,8 @@ This method allows you to track project updates, making it easier to sync the la 4. **Configure environment variables (Optional)** - After deployment is complete, go to project settings - Click "Environment Variables" - - Add the required API keys (e.g., `VITE_OPENAI_API_KEY`) + - Do not preconfigure model API keys for a public Vercel site. `VITE_*` variables are bundled into the frontend build output, so visitors can download those values in the browser. For public sites, let users configure their own API keys in the application UI. + - Only consider preconfigured `VITE_*` model settings for controlled private deployments, and use keys that are rotatable, scoped, and cost-limited. - To add access restriction functionality: - Add an environment variable named `ACCESS_PASSWORD` - Set a secure password as its value diff --git a/mkdocs/docs/en/deployment/web.md b/mkdocs/docs/en/deployment/web.md index d2107910..6f93a0ba 100644 --- a/mkdocs/docs/en/deployment/web.md +++ b/mkdocs/docs/en/deployment/web.md @@ -60,31 +60,11 @@ Recommended flow: 4. Configure environment variables 5. Deploy -### Common environment variables +### Environment variable safety -Text models: +Do not preconfigure model API keys for a public Web site. `VITE_*` variables are bundled into the frontend build output, so visitors can download those values in the browser. For public sites, let users configure their own API keys in the application UI. -```bash -VITE_OPENAI_API_KEY=... -VITE_GEMINI_API_KEY=... -VITE_ANTHROPIC_API_KEY=... -VITE_DEEPSEEK_API_KEY=... -VITE_GROK_API_KEY=... -VITE_SILICONFLOW_API_KEY=... -VITE_ZHIPU_API_KEY=... -VITE_DASHSCOPE_API_KEY=... -VITE_OPENROUTER_API_KEY=... -VITE_MODELSCOPE_API_KEY=... -VITE_MINIMAX_API_KEY=... -``` - -Custom OpenAI-compatible API: - -```bash -VITE_CUSTOM_API_KEY=... -VITE_CUSTOM_API_BASE_URL=https://your-api.example.com/v1 -VITE_CUSTOM_API_MODEL=your-model-name -``` +Only consider preconfigured `VITE_*` model settings for controlled private deployments. Pair that with access control, and use keys that are rotatable, scoped, and cost-limited. ### Optional: site password protection @@ -96,15 +76,40 @@ ACCESS_PASSWORD=your_password The site shows a password page first. This behavior is provided by the root `middleware.js` and `api/auth.js`. -## Deploy to Cloudflare Pages +## Deploy to Cloudflare -The recommended flow is similar to the recommended Vercel flow: fork the project first, then import your fork into Cloudflare Pages. Later, when you sync upstream updates into your fork, Cloudflare Pages redeploys automatically. +Public-repository users can start with Cloudflare's official one-click deploy button: + +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linshenkx/prompt-optimizer) + +This flow clones the source repository into your GitHub/GitLab account, then creates and deploys a Worker with Workers Builds. The root `wrangler.jsonc` configures the Web frontend build command, sets `packages/web/dist` as the Workers Static Assets directory, and enables `index.html` fallback routing for the single-page application. + +Important notes: + +- Deploy to Cloudflare buttons require a public GitHub/GitLab source repository. +- If you want to use a private repository, or restrict the Cloudflare GitHub App to selected repositories manually, use the manual import flow below. + +### Manually import a repository + +Manual import is useful for private repositories, organization repositories, stricter GitHub App access control, or cases where the one-click button does not fit your setup. The current Cloudflare Dashboard may enter the **Workers Static Assets** flow. If the screen says "Create Worker" and shows a deploy command like `npx wrangler deploy`, use the Workers settings. 1. Fork this repository 2. In the Cloudflare Dashboard, open **Workers & Pages** -3. Select **Create application** -> **Pages** -> **Connect to Git** +3. Create an application from your GitHub/Git repository 4. Choose your forked `prompt-optimizer` repository -5. Use the build settings below: +5. If the screen says "Create Worker", keep most settings at their defaults: + +| Setting | Recommended value | +| --- | --- | +| Worker name | Keep `prompt-optimizer` if it is auto-filled; otherwise change it to `prompt-optimizer` | +| Root directory / Path | Keep the default, usually `/` or empty | +| Build command | Clear it; if Cloudflare auto-fills `pnpm run build`, delete it. `wrangler.jsonc` already configures the build command | +| Deploy command | Keep the default `npx wrangler deploy` | +| Non-production branch deploy command | Keep the default `npx wrangler versions upload` | + +If the deployment log says `The Wrangler application detection logic has been run in the root of a workspace`, Wrangler did not read the root `wrangler.jsonc` and tried to auto-detect an app from the monorepo root. Make sure the deployed commit includes `wrangler.jsonc`. If it still fails, set the deploy command to `npx wrangler deploy --config wrangler.jsonc`, and set the non-production branch deploy command to `npx wrangler versions upload --config wrangler.jsonc`. + +If your Cloudflare Dashboard still shows **Create application** -> **Pages** -> **Connect to Git**, you can use the Pages form: | Setting | Recommended value | | --- | --- | @@ -113,20 +118,24 @@ The recommended flow is similar to the recommended Vercel flow: fork the project | Build command | `pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build` | | Build output directory | `packages/web/dist` | -Set these Cloudflare Pages environment variables: +You usually do not need to configure build environment variables manually. Cloudflare detects the `pnpm` and Node.js versions from the repository `packageManager` and `engines` fields. + +If Cloudflare detects the wrong versions, set these build environment variables: ```bash NODE_VERSION=22 PNPM_VERSION=10.6.1 ``` -If you want to preconfigure model API keys, you can also add `VITE_OPENAI_API_KEY`, `VITE_GEMINI_API_KEY`, and other `VITE_*` variables. You can also leave API keys out of the hosting platform and let users configure models in the application UI. +Do not preconfigure model API keys for a public Cloudflare site. Every `VITE_*` variable is bundled into the frontend build output, so visitors can download those values in the browser. For public sites, leave API keys out of the hosting platform and let users configure their own keys in the application UI. + +Only consider preconfigured `VITE_*` model settings for controlled private deployments. Pair that with Cloudflare Access, and use keys that are rotatable, scoped, and cost-limited. ### Optional: Cloudflare Access and Web Analytics -Cloudflare Pages does not use Vercel's `ACCESS_PASSWORD`, `middleware.js`, or `/api/auth`. If you need restricted access, configure Cloudflare Access for your Pages domain in Cloudflare Zero Trust. +Cloudflare deployment does not use Vercel's `ACCESS_PASSWORD`, `middleware.js`, or `/api/auth`. If you need restricted access, configure Cloudflare Access for your Workers or Pages domain in Cloudflare Zero Trust. -Cloudflare Web Analytics can be enabled from **Metrics** -> **Web Analytics** in the Pages project. Cloudflare injects the analytics snippet on later deployments, so no frontend dependency like `@vercel/analytics` is required. +Cloudflare Web Analytics can be enabled from the Cloudflare dashboard, so no frontend dependency like `@vercel/analytics` is required. !!! note The Web version currently uses hash routing. Cloudflare Web Analytics can track site visits and performance data, but it will not automatically treat `/#/xxx` hash route changes as separate page views. diff --git a/mkdocs/docs/zh/deployment/web.md b/mkdocs/docs/zh/deployment/web.md index b993d538..944ab1c6 100644 --- a/mkdocs/docs/zh/deployment/web.md +++ b/mkdocs/docs/zh/deployment/web.md @@ -62,31 +62,11 @@ 4. 配置环境变量 5. 部署 -### 常用环境变量 +### 环境变量安全 -文本模型： +不要在公开 Web 站点中预置模型 API Key。`VITE_*` 变量会进入前端构建产物，访问者可以在浏览器下载到这些值。公开站点应让用户在应用界面的模型管理中自行填写自己的 API Key。 -```bash -VITE_OPENAI_API_KEY=... -VITE_GEMINI_API_KEY=... -VITE_ANTHROPIC_API_KEY=... -VITE_DEEPSEEK_API_KEY=... -VITE_GROK_API_KEY=... -VITE_SILICONFLOW_API_KEY=... -VITE_ZHIPU_API_KEY=... -VITE_DASHSCOPE_API_KEY=... -VITE_OPENROUTER_API_KEY=... -VITE_MODELSCOPE_API_KEY=... -VITE_MINIMAX_API_KEY=... -``` - -自定义 OpenAI 兼容接口： - -```bash -VITE_CUSTOM_API_KEY=... -VITE_CUSTOM_API_BASE_URL=https://your-api.example.com/v1 -VITE_CUSTOM_API_MODEL=your-model-name -``` +只有在受控的私有部署中，才考虑预置 `VITE_*` 模型配置；同时应配合访问控制，并使用可轮换、权限受限、费用受控的密钥。 ### 可选：站点密码保护 @@ -98,15 +78,40 @@ ACCESS_PASSWORD=your_password 站点会先显示密码页。对应逻辑由根目录的 `middleware.js` 和 `api/auth.js` 提供。 -## 部署到 Cloudflare Pages +## 部署到 Cloudflare -推荐流程和 Vercel 的推荐方式类似：先 Fork 项目，再在 Cloudflare Pages 中导入自己的 fork。这样后续你同步 upstream 更新后，Cloudflare Pages 会自动重新部署。 +公开仓库用户可以优先使用 Cloudflare 官方的一键部署按钮： + +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/linshenkx/prompt-optimizer) + +这个流程会把源仓库克隆到你的 GitHub/GitLab 账号下，并使用 Workers Builds 创建和部署 Worker。仓库根目录的 `wrangler.jsonc` 会配置 Web 前端构建命令，把 `packages/web/dist` 配置为 Workers Static Assets 的静态资源目录，并为单页应用启用 `index.html` 回退。 + +需要注意： + +- Deploy to Cloudflare 按钮要求源仓库是公开的 GitHub/GitLab 仓库。 +- 如果你想使用私有仓库，或想手动限制 Cloudflare GitHub App 只访问指定仓库，请使用下面的手动导入方式。 + +### 手动导入仓库 + +手动导入适合私有仓库、组织仓库、需要精细控制 GitHub App 权限，或一键部署按钮失败的场景。当前 Cloudflare Dashboard 可能会进入 **Workers Static Assets** 流程；如果界面显示“创建 Worker”“部署命令 `npx wrangler deploy`”，请使用 Workers 配置。 1. Fork 本仓库 2. 在 Cloudflare Dashboard 中进入 **Workers & Pages** -3. 选择 **Create application** -> **Pages** -> **Connect to Git** +3. 选择通过 GitHub/Git 仓库创建应用 4. 选择你 fork 后的 `prompt-optimizer` 仓库 -5. 使用下面的构建配置： +5. 如果界面显示“创建 Worker”，大多数配置保持默认： + +| 配置项 | 推荐值 | +| --- | --- | +| Worker name | 如果自动填入 `prompt-optimizer`，保持不变；否则改成 `prompt-optimizer` | +| Root directory / Path | 保持默认，通常是 `/` 或留空 | +| Build command | 清空；如果自动填入 `pnpm run build`，请删除。`wrangler.jsonc` 已配置构建命令 | +| Deploy command | 保持默认 `npx wrangler deploy` | +| Non-production branch deploy command | 保持默认 `npx wrangler versions upload` | + +如果部署日志出现 `The Wrangler application detection logic has been run in the root of a workspace`，说明 Wrangler 没有读到项目根目录的 `wrangler.jsonc`，于是尝试在 monorepo 根目录自动识别应用。请确认当前部署的提交已经包含 `wrangler.jsonc`；如果仍然报错，再把部署命令改成 `npx wrangler deploy --config wrangler.jsonc`，把非生产分支部署命令改成 `npx wrangler versions upload --config wrangler.jsonc`。 + +如果你的 Cloudflare Dashboard 仍然显示 **Create application** -> **Pages** -> **Connect to Git**，也可以继续使用 Pages 表单： | 配置项 | 推荐值 | | --- | --- | @@ -115,20 +120,24 @@ ACCESS_PASSWORD=your_password | Build command | `pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build` | | Build output directory | `packages/web/dist` | -建议在 Cloudflare Pages 环境变量中设置： +通常不需要手动配置构建环境变量。Cloudflare 会根据仓库里的 `packageManager` 和 `engines` 检测 `pnpm` 和 Node.js 版本。 + +如果 Cloudflare 检测到的版本不正确，再在构建环境变量中设置： ```bash NODE_VERSION=22 PNPM_VERSION=10.6.1 ``` -如果你想预置模型 API Key，可以继续添加 `VITE_OPENAI_API_KEY`、`VITE_GEMINI_API_KEY` 等 `VITE_*` 变量。也可以不在部署平台配置 API Key，让用户在应用界面的模型管理中自行填写。 +不要在公开 Cloudflare 站点中预置模型 API Key。所有 `VITE_*` 变量都会进入前端构建产物，访问者可以在浏览器下载到这些值。公开站点应让用户在应用界面的模型管理中自行填写自己的 API Key。 + +只有在受控的私有部署中，才考虑预置 `VITE_*` 模型配置；同时应配合 Cloudflare Access，并使用可轮换、权限受限、费用受控的密钥。 ### 可选：Cloudflare Access 和 Web Analytics -Cloudflare Pages 不会使用 Vercel 的 `ACCESS_PASSWORD`、`middleware.js` 或 `/api/auth`。如果你需要限制访问，推荐在 Cloudflare Zero Trust 中为 Pages 域名配置 Cloudflare Access。 +Cloudflare 部署不会使用 Vercel 的 `ACCESS_PASSWORD`、`middleware.js` 或 `/api/auth`。如果你需要限制访问，推荐在 Cloudflare Zero Trust 中为 Workers 或 Pages 域名配置 Cloudflare Access。 -Cloudflare Web Analytics 可以在 Pages 项目的 **Metrics** -> **Web Analytics** 中启用。Cloudflare 会在后续部署中自动注入统计脚本，不需要安装 `@vercel/analytics` 之类的前端依赖。 +Cloudflare Web Analytics 可以在 Cloudflare 控制台启用，不需要安装 `@vercel/analytics` 之类的前端依赖。 !!! note 当前 Web 版使用 hash 路由。Cloudflare Web Analytics 可以统计站点访问和性能数据，但不会自动把 `/#/xxx` 这类 hash 内页面切换当作独立页面浏览。 diff --git a/wrangler.jsonc b/wrangler.jsonc new file mode 100644 index 00000000..aefe18ce --- /dev/null +++ b/wrangler.jsonc @@ -0,0 +1,11 @@ +{ + "name": "prompt-optimizer", + "compatibility_date": "2026-05-27", + "build": { + "command": "pnpm -F @prompt-optimizer/core build && pnpm -F @prompt-optimizer/ui build && pnpm -F @prompt-optimizer/web build" + }, + "assets": { + "directory": "packages/web/dist", + "not_found_handling": "single-page-application" + } +}