Proa documentation

Proa 营销网站

Proa 的 Rust SSR 营销网站。

Agent 接口

编写的文档输出使用带类型的 Proa 组件和特定格式的宏。 每个页面都拥有自己的 HTML 和 Markdown 实现，并在两者之间共享内容字段。 首页由明确的 Markdown 章节组成，涵盖主视觉区、渲染示例、展示对比、基准测试图表、UI 目录、功能和快速入门。Markdown 会一并展示所有基准测试用例，并省略视觉演示固定数据和控件。只有现有的 HTML 专用高亮代码片段使用原生转换器。About/Contact 页面也共享数据；身份验证和文档索引位于 docs 模块中。 OpenAPI 和 MCP 输入架构 使用 const_json! 字面量，运行时发现 URL 则使用带类型的序列化器。 站点地图使用 xml_sync!，404 页面使用 html_sync! / md_sync!。

首页支持 Accept: text/markdown、/index.md 和 ?mode=agent。 /llms.txt 和 /.well-known/llms.txt 导出同一个页面渲染结果；专用文档索引位于 /docs/llms.txt。Agent 目录位于 /.well-known/ard.json 和 /.well-known/ai-catalog.json；RFC 9727 API 目录位于 /.well-known/api-catalog。这些文档使用解析后的公开站点 URL， 包括 Railway 预览来源。

公开发现文件允许跨源浏览器读取和条件请求预检。 /mcp 传输保留独立的 Host 和 Origin 检查。其实验性服务卡片使用与运行时握手相同的标识。

位于 /.well-known/agent-skills/index.json 的技能索引使用草案版 Agent Skills Discovery 0.2 格式，并为所提供的 SKILL.md 文件提供 SHA-256 摘要。这些指令介绍了 Proa 源码检出目录中的工作流，并引用其文档和脚本。

/api/v1/search、/api/v1/docs 和 /api/v1/docs/page 提供对公开文档的带类型分页访问。/mcp 通过官方 Rust MCP SDK 的无状态 Streamable HTTP 传输暴露相同来源，提供两个只读工具和分页 Markdown 资源。/mcp/server-card 描述连接信息。不会暴露凭据或写入功能。API 和 MCP 响应会声明每个实例强制执行的共享预算：每分钟 600 个请求。

可选的 /static/agent-tools.mjs 会通过 WebMCP 注册搜索和检索操作。其测试使用 node --test proa_marketing/tests-js/agent-tools.test.mjs 运行。HTTP 和 MCP 测试通过关联的流水线运行：

cargo proa test --root . --locked -p proa_marketing --bin proa_marketing

外部接口约定请参阅公开 API 指南。部署冒烟测试还会验证发现索引、Markdown 首页、目录、搜索响应和 MCP 服务卡片。Ora 评分只有在部署后进行新的外部扫描时才会更新；搜索索引和目录列表不受应用程序控制。

Proa UI 首页栏

首页包含 Proa UI 的 marketing/src/pages/home.rs 中完整的 home-rail-section：十个非交互式组件预览和目录磁贴。其渲染后的 HTML 和作用域 CSS 均已检入，因此常规构建无需下游组件库或另一份检出目录。说明文字链接会打开位于 ui.proa.so 的实时目录。

要刷新它，请在本地运行 Proa UI 营销应用，然后从 Proa 工作区根目录运行以下命令，并提供该应用的 URL：

node scripts/import-proa-ui-rail.mjs http://127.0.0.1:3333

导入器会保留源栏目的顺序、响应式样式、主题和键盘导航。它会从非交互式预览中移除水合元数据，并将其样式限制在此分区内。刷新快照后，请检查两种主题和移动端布局。

文档搜索

Cmd+K 搜索完全在浏览器中运行。构建文档时会生成 /docs/_search/documents.json（每个页面包含标题、描述、章节、标题、 frontmatter keywords 和正文）；首次打开时，public/search.mjs 会获取该文件， 并使用随附的 Orama 包建立索引。排序逻辑位于 public/search-index.mjs，Node 搜索测试也会导入它， 因此你测得的分数就是实际发布的分数：

pnpm run search:battery                  # local server on :5555
node scripts/search_battery.mjs --source prod
node scripts/search_battery.mjs --source path/to/documents.json --verbose
node scripts/search_battery.mjs --config tweak.json   # override DEFAULT_CONFIG keys

测试样例位于 scripts/search-battery.json（每个查询对应一个显然正确的页面， 若两个页面并列，则列出较短的页面清单）；若前 1 名或前 3 名的排名下降， 测试阈值就会使运行失败。为页面添加其规范文档标识符，并通过 keywords: [html_sync, html!] frontmatter 列表设置；该字段的权重高于正文。 升级 @orama/* devDependencies 后，使用 pnpm run search:vendor 重新生成 Orama 包。

rsjs SearchModal 岛仅负责对话框（打开、关闭、焦点）；请参阅 public/search.mjs 顶部的归属说明。

内容

营销文档和博客内容由 proa_docs_build 在构建时编译。 请将由路由管理的 MDX 放在以下 crate 本地目录中：

• src/docs -> /docs
• src/blog -> /blog

每个集合都遵循 fumadocs 风格的 meta.json 约定，用于侧边栏排序和嵌套分组。

本地 Docker 构建

从仓库根目录构建：

docker build \
  -f proa_marketing/Dockerfile \
  -t proa-marketing .
docker run --rm -p 5555:5555 \
  -e HOST=0.0.0.0 \
  -e PORT=5555 \
  -e SITE_URL=http://localhost:5555 \
  -e PROA_BUILD_REVISION=0123456789abcdef0123456789abcdef01234567 \
  proa-marketing

健康检查：

curl -fsS http://127.0.0.1:5555/healthz

完整的公开契约冒烟测试：

python3 deploy/marketing_smoke.py \
  --url http://127.0.0.1:5555 \
  --expected-revision 0123456789abcdef0123456789abcdef01234567 \
  --attempts 1

Docker 会从构建上下文根目录读取 .dockerignore。此仓库包含根目录 .dockerignore，因此本地的 target/、.tools/ 和 node_modules/ 目录不会发送给 Docker 守护进程。

Dockerfile 完全基于此仓库构建。无需相邻的代码检出目录、 额外的 BuildKit 上下文或仓库凭据。

Docker 构建器会使用 Tailwind 独立 CLI，根据 proa_marketing/styles/input.css 重新生成 proa_marketing/public/styles.css。无需安装 Node 或 TypeScript 工作区依赖。构建阶段会下载适用于目标架构的固定版本 Tailwind 3.4.18 Linux 可执行文件，并在执行前验证其发布的 SHA-256，因此 需要能够访问外部 HTTPS。

严格的链接发布构建在全新本地构建器上约需 11 分钟；在缓存预热前，耗时可能超过 Free 或 Trial 构建时限。若要可靠地从源代码构建，请使用 Hobby 或更高版本； 也可以让 CI 发布预构建镜像，并让 Railway 指向该镜像。

发布可执行文件来自链接的 cargo proa build 流水线。不要将其替换为普通的 cargo build：只有链接流水线会解析浏览器水合所需的 RSJS 客户端辅助模块依赖。

Railway

Google Analytics

网站默认使用 GA4 网络数据流 G-5XSLT8GCN3。在生产服务的运行时变量中设置 GOOGLE_ANALYTICS_MEASUREMENT_ID，即可覆盖此公开测量 ID；显式设置为空值或格式错误的值会停用分析功能。更改后请重启或重新部署。网站配置中不得包含 Google OAuth 令牌、服务账号密钥或 Analytics API 密钥。

共享文档头部在营销、文档和生态系统页面中使用 proa_third_party::google::GoogleAnalytics。 Google SDK 会等到 window.load 后再加载，以免与页面的初始资源加载争用。应用会通过 AnalyticsConsent::Granted 显式启用数据收集；否则，共享 crate 需要调用方提供同意决定。浏览器引导程序只会在 proa.so 和 www.proa.so 上、且不在 iframe 中时加载 Google 脚本，因此 localhost、Railway 预览和嵌入式演示不会增加生产页面浏览量。Google Signals 和广告个性化信号均已停用。GA4 的常规配置会在每次加载文档时自动发送一次页面浏览量。有关可复用 API、同意处理和加载权衡，请参阅第三方集成文档。

要验证部署，请打开生产页面，并检查是否有 googletagmanager.com/gtag/js 请求，以及包含已配置测量 ID 的 google-analytics.com/g/collect 请求。请在媒体资源的实时报告中确认此次访问。浏览器跟踪防护可能会拦截这些请求。

部署

生产环境运行在 Railway 上，地址为 https://proa.so。所有 Proa 应用 （包括 proa-ui）都已从 Coolify 迁移到 Railway；Coolify 不再是活跃的 部署依赖项。

在 main 上，GitHub Actions 使用 Cloud Build 构建并检查营销站点镜像，将验证通过的镜像发布到私有 GHCR，并在 CI 通过后将其不可变 摘要部署到 Railway。有关发布工作流和注册表配置，请参阅 营销站点发布镜像。

从源代码构建 Railway 环境（包括原生 PR 环境）时，已纳入版本控制的 railway.toml 会选择此 crate 的 Dockerfile，同时将仓库根目录作为 Docker 构建上下文。 共享的 Cargo 工作区要求使用此上下文：

• 配置文件：/railway.toml
• 构建器：Dockerfile
• Dockerfile：/proa_marketing/Dockerfile
• 健康检查路径：/healthz
• 启动命令：继承自 Dockerfile CMD

Railway 会注入 PORT、RAILWAY_GIT_COMMIT_SHA、 RAILWAY_ENVIRONMENT_NAME 和 RAILWAY_PUBLIC_DOMAIN。镜像会提供其余运行时默认值。在生产环境中， robots.txt 和站点地图中的绝对 URL 会依次使用显式设置的 SITE_URL、部署的 RAILWAY_PUBLIC_DOMAIN，最后回退到 https://proa.so。非生产 Railway 环境优先使用自身注入的公有域名，以防继承的生产变量将生产环境的规范 URL 泄漏到 PR 站点地图中。

由于旧版 preview.proa.so 别名仍是 Railway 注入的主域名，生产环境会临时设置 SITE_URL=https://proa.so。标准 PR 环境会复制基础变量，因此解析器会在生产环境之外优先使用环境专属的 RAILWAY_PUBLIC_DOMAIN。一旦 Railway 将 proa.so 报告为生产环境公有域名， 请移除显式设置的 SITE_URL 变量。

不要设置 PORT：Railway 会分配端口并将流量路由到该端口。若要覆盖默认值，只设置所需的值：

HOST=0.0.0.0
RUST_LOG=info
STATIC_DIR=/app/static
SHOWCASE_PUBLIC_DIR=/app/showcase
PROA_CONSOLE_LOAD_TESTS=0

对于不提供 RAILWAY_PUBLIC_DOMAIN 的平台，或者要使用上述临时 Railway 生产环境覆盖设置时，请使用 SITE_URL=https://<domain>。

/readyz 会将 Railway 的提交 SHA 作为 x-proa-revision 返回，并设置 Cache-Control: no-store。PROA_BUILD_REVISION 仍可用作跨平台的显式覆盖项。

从仓库根目录关联并检查服务：

railway link --project Proa --environment production --service proa
railway status --json

生产镜像部署由 .github/workflows/ci.yml 中的 deploy-release 作业控制；该作业会等待必需的 CI 门禁和验证通过的发布镜像。

在 Project Settings → Environments → PR Environments 中启用原生预览。在生产服务上保留 Railway 提供的域名； Railway 会使用它为每个临时 PR 环境配置独立域名。暂时不要启用 Focused PR Environments：此服务依赖整个仓库中的 crate 和构建输入， 而不仅仅是 proa_marketing/ 下的文件。

公共营销控制台中的 PROA_CONSOLE_LOAD_TESTS 默认禁用。仅在本地或内部部署中将其设为 1，以便启用 /api/loadtest。

公共 playground 提供 Proa 和已部署的 Hono React 伴随项目 （Node 和 Bun），并根据每个展示项目支持的引擎进行筛选。将 PROA_COMPANIONS=0 可使选择器中只保留 Proa。独立 playground 会保留其他对比引擎，供本地基准测试使用。

eBay playground 位于 /playground/ebay/ebay-srp，并使用交互式 渲染器。旧版 /playground/ebay-rsjs/ebay-srp-rsjs URL 会重定向到该地址。

src/docs/framework/ 下公开的 Coolify 部署指南记录了供自行运行 Coolify 实例的用户使用的可选部署预设。 本仓库之前的 Coolify 运维文档已归档至 deploy/COOLIFY.md；旧版资源清理工作记录在 退役操作手册 中。