Files

T

AI Directory Platform 5b1c8ccdf2 docs: 五站点上线域名映射（Cloudflare DNS + Nginx 反代）

2026-09-08 19:32:36 +00:00

12 KiB

Raw Permalink Blame History

AI Directory Platform — 交付报告

基于 coolchange-ai/toolso-ai-open 二次开发的可复用 AI Directory 基础底座，按《AI-Directory-Platform开发计划与技术设计文档》完成 MVP + V1 核心能力，并以 五套不同 UI 的完整站点 完成底座「快速、易用、可用、可靠」验证。

代码位置：AI-Directory-Platform/packages/core/（底座库）+ AI-Directory-Platform/sites/（5 个独立网站）
技术栈：Next.js 16 · React 19 · TypeScript · Tailwind CSS · PostgreSQL + Drizzle ORM · Better Auth · next-intl
验证状态：typecheck 0 错误 · bun test 32/32 通过 · 5 套主题全部构建成功 · 端到端交互测试 PASS

一、仓库结构（monorepo）

AI-Directory-Platform/
├── packages/core/          # @aidir/core —— AI Directory 底座库
│   ├── src/pages/          #   全部页面组件体（1:1 镜像路由树）
│   ├── src/kit/            #   站点外壳工厂（Header/Footer/chrome/首页数据）
│   ├── src/lib|features/   #   ranking/seo/analytics/voting/reviews/... 全部业务
│   ├── content/blog/       #   MDX 文章
│   ├── messages/           #   基础文案（en/zh，546 键）
│   └── scripts/            #   db/seed/生成器/启动器/e2e
└── sites/                  # 5 个独立 Next.js 网站（各自 package.json/构建/部署）
    ├── ai-stack/           #   AI Stack —— Classic 目录        :3001
    ├── launchai/           #   LaunchAI —— Product Hunt 式      :3002
    ├── the-ai-ledger/      #   The AI Ledger —— Editorial 媒体  :3003
    ├── devai-tools/        #   DevAI.tools —— 开发者垂直        :3004
    └── findai/             #   findai —— 极简搜索              :3005

每个站点应用只有三类自己的代码：

src/site/brand.tsx —— 品牌/导航/页脚/SEO 文案（SiteConfig）
src/site/home.tsx —— 站点首页组件
src/app/** —— 薄路由（约 56 个文件，全部为 re-export 底座页面组件 + 内联路由段配置）

站点之间零重复业务代码；新增第 6 个网站 = 在生成器 SITES 里加一个条目并运行 bun packages/core/scripts/generate-site.mjs <key>，零 Core 代码修改。

一'、快速开始

cd AI-Directory-Platform

bun install                          # workspace 安装（root 一次）

# 数据库（五个网站共享同一套 PostgreSQL —— 设计文档 §42）
cd packages/core && cp .env.example .env.local && bun run db:push && bun run seed:platform && cd ../..

# 构建 5 个网站（构建时数据库需在线；构建期间不要运行站点，避免连接数耗尽）
for s in ai-stack launchai the-ai-ledger devai-tools findai; do (cd sites/$s && cp -n .env.example .env.local && bun run build); done

# 一键启动（或分别 cd sites/<name> && bun run start）
bash packages/core/scripts/start-all-sites.sh

# 注意：构建期间数据库需在线，且不要同时运行站点（Next 构建 worker 会占满 PG 连接）
# 注意：修改 .env 后需 rm -rf .next 再构建（Turbopack 构建缓存不感知 env 变化）

# 质量
bun test packages/core/tests         # 32 个单元测试
bun run typecheck                    # core + 5 站全部 0 错误

演示账号（种子内置，密码均为 password123）：

账号	角色
`admin@aidirectory.dev`	管理员（可访问 `/admin` 全部后台）
`alice@demo.dev` 等 5 个	普通用户

二、与设计文档验收标准对照

UI（§74）

要求	状态
所有图标 SVG / Lucide，无 Emoji、Unicode 图标、字符箭头	✅ 全部使用 `lucide-react`；种子分类 icon 置空；唯一例外是种子工具名 "DALL·E 3" 的 `·` 为产品名本身
Responsive（375/768/1280/1440 实测截图）	✅ Mobile First，Header 移动端汉堡抽屉 + 搜索
Light/Dark/System	✅ 继承底座 next-themes，全组件适配

Functional（§74 / MVP §57）

要求	实现位置
Google Login	✅ 底座已有（env 门控）
GitHub Login	✅ `src/lib/auth.ts`（env 门控）+ 登录页按钮
Vote	✅ `src/features/voting/`（登录投票、原子 toggle、滑动窗口限流 40 次/10min、乐观 UI、`/api/tools/:id/vote`）
Favorite	✅ 底座已有
Review	✅ `src/features/reviews/`（评分/优缺点/使用场景/Helpful/每用户一条/聚合评分回写）
Submit	✅ `src/features/submission/`（提交 → Admin 审批自动发布 → 域名重复检测）
Claim	✅ `src/features/claim/`（认领申请 → 审批 → Owner 徽标 + 白名单字段编辑 `ownerUpdateTool`）
Search	✅ `/api/search`（PostgreSQL 多维 ILIKE + 热度排序 + search 埋点）
Filter	✅ 分类 / 定价 / Use Case / Audience / 排序（最新、最热）
Ranking	✅ `src/lib/ranking/`（七个榜单 + Ranking Engine 独立）

SEO（§74 / §23 / §24 / §52）

要求	实现
SSR / ISR	✅ 全站 RSC + ISR（1h）+ 变更 revalidatePath
Metadata / Canonical / hreflang	✅ `src/lib/metadata.ts`（继承底座）
Sitemap	✅ `src/app/sitemap.ts` 扩展至 270 条：工具 / 分类 / 用例 / 受众 / 合集 / Top20 Alternatives / 对比页
Schema	✅ SoftwareApplication(+AggregateRating) / Review 数据 / FAQPage / BreadcrumbList / ItemList / CollectionPage / WebSite / Organization
Programmatic SEO	✅ `src/lib/seo/page-generator.ts`：由实体真实数据生成 Title/H1/Intro/FAQ（避免低质模板页：Alternatives/Comparison 只为 Top 工具生成）
内链系统	✅ Tool ↔ Category ↔ Use Case ↔ Audience ↔ Alternatives ↔ Best ↔ Blog 的 SEO Graph

Performance（§47）

Server Components First、ISR、next/image、分页、数据库索引（vote/rating/domain 等 7 个新索引）。构建产物静态化率见构建输出（SSG 为主，交互 API 为 ƒ）。

Security（§74）

RBAC（requireAdmin/isAdmin）、Zod 全量输入校验、投票限流 + pending 唯一索引防重、认领 pending 唯一约束、Vote Audit 审计页（用户/IP/来源/速度告警）、外链 nofollow + 跳转埋点。

三、底座架构（Core 与 Site 分离）

src/
├── lib/
│   ├── ranking/          # Ranking Engine（score.ts 纯函数 + queries.ts SQL + boards.ts）
│   ├── seo/              # Programmatic SEO 页面生成器
│   ├── analytics/        # 事件埋点（recordEvent/recordToolView）
│   ├── tools/duplicate.ts# 重复工具检测（域名归一化/slug/名称）
│   └── db/schema/        # community(投票/评论/提交/认领) discovery(用例/受众/合集) analytics(事件)
├── features/             # Feature-First：voting / reviews / submission / claim / discovery / alternatives
├── themes/               # ★ Site Theme 层：registry + chrome + shared + 5 套主题
│   ├── classic/          # AI Stack —— 专业目录（Clean/Dense/Professional）
│   ├── product/          # LaunchAI —— Product Hunt 式每日发布社区
│   ├── editorial/        # The AI Ledger —— 媒体型（Featured Story/编辑精选/购买指南）
│   ├── niche/            # DevAI.tools —— 垂直（AI for Developers，终端风 Hero）
│   └── minimal/          # findai —— 极简搜索引擎（一个框 + 热门搜索）
└── app/[locale]/         # 路由：/tools /rankings /best /ai-tools-for /submit /admin/* /api/*

五套站点 = 同一套数据库、认证、Admin、Tool 模型、Vote/Review、Ranking、Search、SEO、Analytics，只改变 Theme/Layout/Navigation/Content/Brand —— 即设计文档 §42 的验证标准。新增第 6 个站点只需在 src/themes/ 增加一个目录并注册 registry，零 Core 代码修改。

主题在构建时注入（SITE_THEME=<id> NEXT_DIST_DIR=.next-<id> bun run build），一次构建对应一个站点部署，SSG/ISR 性能不受影响。

四、五个网站验证结论（§41 / 最终要求）

网站	目录	线上地址	本地端口	定位	首页形态
AI Stack	sites/ai-stack	https://ai-stack.opentest.cc	3001	标准目录	Hero 搜索 + Trending/分类/新工具/用例/合集/评论
LaunchAI	sites/launchai	https://launchai.opentest.cc	3002	产品社区	今日发布 Feed + 大投票块 + Leaderboard 侧栏
The AI Ledger	sites/the-ai-ledger	https://the-ai-ledger.opentest.cc	3003	AI 媒体	Featured Story + 编辑精选 + 购买指南 + 社区引语
DevAI.tools	sites/devai-tools	https://devai-tools.opentest.cc	3004	开发者垂直	终端风 Hero + 工作流/用例/技术栈
findai	sites/findai	https://findai.opentest.cc	3005	极简搜索	居中大搜索框 + 热门搜索 + Trending

域名与部署：五个子域名经 ldns 配置 Cloudflare DNS（Proxied）+ Nginx 反向代理（/etc/nginx/conf.d/<site>.conf → 127.0.0.1:300X）；各站点 .env.local 的 NEXT_PUBLIC_APP_URL / BETTER_AUTH_URL 指向各自 https 域名， canonical / sitemap / JSON-LD / OAuth 回调输出均为线上域名。

验证结果：5 个网站是 5 个独立 Next.js 应用（独立 package.json、独立 .next 构建、独立进程/端口），共享同一套 PostgreSQL / Better Auth / Admin（§42 验证标准）。站点间零 if site === "xxx" 分支；每站均通过构建、11 条路由 × 5 站 = 55 项 200 冒烟、1440/390 双断点截图、控制台 0 报错、登录→投票（DB 3→4→3）→重复提交检测 e2e PASS。

五、端到端验证记录

验证项	结果
19 条核心路由冒烟（含 zh、sitemap、search API、outbound 307 跳转）	✅ 全部 200
JSON-LD（SoftwareApplication+AggregateRating/FAQPage/Breadcrumb/ItemList）	✅ 详情页实测输出
Sitemap 270 条（含用例/受众/合集/alternatives/vs）	✅
登录（alice@demo.dev）→ 投票 toggle（DB 3→4→3，按钮同步）	✅ PASS
重复提交检测（提交 chatgpt.com 被拦截并列出已有工具）	✅ PASS
评论表单（已有评论回显编辑模式、星级、优缺点）	✅ 截图验证
五主题品牌/版式差异化（AI Stack/LaunchAI/The AI Ledger/DevAI.tools/findai）	✅ 截图验证
`bun test`（ranking 评分/贝叶斯/路由解析/域名归一化/SEO 生成器）	✅ 32/32
`bun run typecheck`	✅ 0 错误
`bun run build` × 5 主题	✅ 全部成功

截图存档：/tmp/aidir-shots/（16 张，含移动端 390×844）。

六、API 一览（§45）

POST/DELETE /api/tools/:id/vote     投票/取消（登录，限流）
GET        /api/search?q=           PostgreSQL 搜索（含埋点）
GET        /api/outbound?tool=slug  外链跳转 + tool_click 埋点 + 计数
GET        /api/tools（列表查询走 server actions：getPublishedTools 支持 category/pricing/usecase/audience/sort）
POST       /api/auth/[...all]       Better Auth（邮箱密码 + Google + GitHub）

提交/认领/评论/收藏走 Server Actions（features/*/actions.ts），与 REST 共存。

七、事件与分析（§37/§38）

event 表统一采集 10 类事件：tool_view / tool_click / tool_vote / tool_unvote / tool_favorite / tool_review / tool_share / search / category_view / submit_tool / claim_tool。详情页浏览与外链点击自动同步 tool.viewCount/clickCount 冗余列； /admin/analytics 输出近 30 天事件总量、工具 CTR 排行（views≥10）、热门搜索词。

八、已知边界与后续（V2 路线）

主题文案 i18n：五套主题的 Brand 文案当前为英文（品牌层）；核心页面（工具/榜单/表单/后台）中英双语完整。后续可把主题文案迁入 messages/<locale>.json。
OAuth 凭据：Google/GitHub 登录需在生产配置真实 Client ID/Secret（env 门控，缺省自动隐藏按钮）。
V2 待办（按设计文档 §59）：Meilisearch 语义搜索、AI 推荐、自动分类、爬虫导入、Monetization 层。
评论可信度（§19）：已实现 Verified User（邮箱认证徽标）+ Helpful 投票；Verified Usage/Purchase 留待 V2。
上游遗留兼容性升级：framer-motion 11→12（本次已升级以修复 React 19 类型）。

九、Git 状态

全部改动已在 core/ 仓库本地提交（见 git log），上游远程 origin 保留，可随时 diff 审查或推送 fork。

12 KiB Raw Permalink Blame History Unescape Escape