Files

T

ZhuiGuangAI Dev e263e28c81 全面审查优化: 43项修复（安全/性能/可靠性）+ 文档更新

🔴 P0 安全: .env入gitignore, CSP/HSTS, Logo安全(5MB限制+SVG消毒+SHA256), middleware权限收紧(VIP不能访问admin), 发布去重, GitHub认证, 删除危险API, skill-discoverer绕过审核修复, prisma默认连接修复
🔴 P0 可靠性: deepseek/github超时重试, 脚本层DeepSeek保护, 脚本启动验证, OAuth竞态修复
🔴 P0 性能: skill-discoverer N+1优化(↓94%), 后台API分页限制, getUserStats聚合优化
🟡 P1: 分类动态加载, 星级字段统一, fetch-logos并发Bug修复, 批量发布冲突不删除, check-tools重试, 前端空指针修复(13处), logo-fetcher日志, rate-limit清理, 公开API缓存

2026-05-26 00:30:36 +08:00

12 KiB

Raw Blame History

追光AI 项目开发规则

端口规范

应用端口范围: 8301-8310（预留扩展）
默认端口: 8301
重启脚本仅扫描8301-8310范围
强制要求：本项目端口必须锁定在8301-8310区间内，禁止使用其他端口，因为本服务器同时运行其他产品

服务器与基础设施

域名: www.zhuig.com (HTTPS，SSL证书自动续期)
云服务器: 119.45.242.239 (登录名: ubuntu, 密钥: Pem/zg.pem)
数据库: 阿里云RDS MySQL — rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306
Redis: 云服务器上已有(Docker容器redis-cache:6379)，与其他项目共用，有密码认证
本地Git同步目录: K:\git-repos
开发机: E:\ZG_Dev\ZhuiGuangAI\zhuiguang-ai
部署目录: /home/ubuntu/zhuiguang-ai
访问地址: https://www.zhuig.com (HTTP自动跳转HTTPS)
注意事项: 服务器有其他应用运行，部署时不可占用非8301-8310端口，不可影响其他服务
SSH连接示例: ssh -i "Pem/zg.pem" ubuntu@119.45.242.239
PM2管理: pm2 list / pm2 restart zhuiguang-ai / pm2 save
其他应用: agent-system, nacos, zhuiguang-quant (部署时请勿影响)

技术栈

Next.js 14 (App Router) + TypeScript
Tailwind CSS + shadcn/ui
Prisma 7.8 + MySQL (阿里云RDS)
NextAuth.js v4 (Credentials Provider)
DeepSeek API (deepseek-v4-pro) — 用于技能五维评测生成（服务端脚本调用）

代码风格

不添加注释（除非明确要求）
使用中文作为UI文案和提示词语言
TypeScript严格模式，零编译错误
组件使用 "use client" 标记客户端组件
路径别名: @/* → ./src/*
禁止在代码中硬编码任何AI API Key
禁止在代码中调用任何外部AI API（DeepSeek、OpenAI等） — 前台/后台页面代码中禁止调用；服务端脚本(scripts/)中允许通过环境变量调用DeepSeek API和GitHub API
所有发现/导入功能通过页面提示词+JSON粘贴方式完成，不调用外部接口

构建与检查

修改代码后必须运行 npx tsc --noEmit 确认零错误
重启服务使用 pwsh -ExecutionPolicy Bypass -File restart.ps1
开发服务器: npm run dev (端口8301)

数据库

云数据库: 阿里云RDS MySQL
连接: mysql://mohe001:***@rm-0jlbgr2rv6dj3t6jngo.mysql.rds.aliyuncs.com:3306/zhuiguang_ai
Prisma单例模式防止热重载多实例
修改Schema后: npx prisma migrate dev --name <描述>

认证

管理员: admin@zhuiguang.ai / admin123
JWT Session策略
middleware.ts保护/admin路由（跳过/admin/login）
后台API需requireAdmin中间件验证（src/lib/admin-auth.ts）
用户注册/登录: NextAuth Credentials Provider，支持邮箱+密码

API约定

前台API: /api/ 前缀，无需认证
后台API: /api/admin/ 前缀，需NextAuth认证
分页参数: page(默认1), pageSize(默认20)
返回格式: { data, total, page, pageSize } 或 { success, error }
批量操作: body中传 ids 数组

页面路由

前台: /, /tools, /tools/[slug], /categories/[slug], /skills, /skills/[slug], /login, /user, /user/favorites, /user/[id](会员空间), /user/collections, /daily, /reviews, /community, /community/[category], /community/topic/[id]
后台: /admin/login, /admin/pending, /admin/pending-skills, /admin/tools, /admin/skills, /admin/categories, /admin/skill-categories, /admin/discover-tools, /admin/check-tools, /admin/discover-skills, /admin/update-skills, /admin/discover-news, /admin/system-config, /admin/tasks, /admin/tasks/logs, /admin/tasks/[taskKey], /admin/reviews

五大操作指令

用户使用以下五个命令时，必须跳转到对应页面理解流程并按流程执行。所有页面均为"提示词+JSON粘贴导入"模式，不调用任何外部AI API。

探索AI工具

页面: /admin/discover-tools
流程: 选分类 → 复制提示词发给AI → 粘贴JSON → 导入审核列表 → 抓取Logo
导入API: POST /api/admin/discover-tools body: { tools: [...], categoryId }
API接收前端提交的工具JSON数组，自动去重导入待审核列表
Logo抓取API: POST /api/admin/pending/fetch-logos
工具分类(20个): 文本生成(165), 图像生成(174), 视频生成(183), 音频与语音(191), 代码开发(199), AI Agent(208), 办公效率(216), 设计与创意(224), 营销与SEO(231), 数据分析(238), 教育与学习(245), 搜索与信息(252), 安全与合规(258), 医疗健康(264), 金融与法律(270), 电商与零售(276), 3D与游戏(282), 科学研究(288), 模型与框架(294), 聊天机器人(302)

检测AI工具

页面: /admin/check-tools
流程: 选择范围(已发布/待审核) → 一键检测+抓取Logo → 处理失效工具
检测API: POST /api/admin/check-tools body: { type: "published" | "pending" }
系统自动逐一GET请求检测网站可访问性，同时自动抓取缺失Logo并记录成功方法名
删除API: DELETE /api/admin/tools/{id} / /api/admin/pending/{id}

探索AI技能

页面: /admin/discover-skills
流程: 选分类 → 复制提示词发给AI → 粘贴JSON → 导入审核列表
导入API: POST /api/admin/discover-skills body: { skills: [...], categoryId }
API接收前端提交的技能JSON数组，自动去重导入待审核列表
技能分类(20个父分类): 代码生成(1), 测试(10), 代码质量与分析(20), 安全(29), 文档(36), 架构与设计(43), 需求工程(49), DevOps与部署(56), 调试与错误处理(62), 形式化验证(69), 维护与重构(76), 版本控制与协作(82), 开发工具(86), UI/UX设计(91), 科学研究(95), 金融(103), 云服务(109), 移动开发(115), AI/ML工程(120), 营销与增长(127)

更新Skill技能

页面: /admin/update-skills
流程: 选择范围(已发布/待审核) → 一键更新 → 自动同步星级
更新API: POST /api/admin/update-stars body: { type: "published" | "pending" }
系统自动从GitHub/Gitee/GitCode API获取最新星级评分并写入数据库

AI新闻发现

页面: /admin/discover-news
流程: 复制提示词发给AI → 粘贴JSON → 导入今日新闻
导入API: POST /api/admin/discover-news body: { items: [...] }
API接收前端提交的新闻JSON数组，自动生成今日AI日报
新闻分类: 产品发布/融资投资/技术突破/政策法规/开源项目/行业事件

通用执行规则

禁止调用任何外部AI API，所有发现/导入功能通过页面提示词+JSON粘贴方式完成
页面提供提示词模板（含排除列表），用户复制发给AI助手获取JSON，粘贴到页面导入
导入API接收JSON数组，自动去重（名称+网址），导入待审核列表
导入工具后建议执行Logo抓取，确保所有工具有图标
所有提示词要求: 优先推荐国产AI工具/技能，国内可直连，中文友好
检测工具时：系统自动GET请求检测网站可访问性，同时抓取缺失Logo
更新技能时：系统自动从GitHub/Gitee/GitCode API获取最新星级

设计系统

浅色主题，HSL CSS变量
圆角: rounded-xl / rounded-2xl
边框: border-border/40 (40%透明度)
背景: bg-white/80 (毛玻璃) / bg-white/60 (卡片) / bg-muted/50 (输入框)
阴影: shadow-sm (卡片) / shadow-md (悬浮)
动画: transition-all duration-200
自定义工具类: .glow-sm, .gradient-text, .glass, .card-shine, .dot-grid, .animate-fade-in
颜色规范: 文字用 -600/-700 (非-400)，背景用 -50 (非-500/10)，边框用 -200/60 (非-500/20)
输入框: bg-muted/50 focus:bg-white focus:ring-2 focus:ring-primary/10

环境变量

GITHUB_TOKEN: GitHub Personal Access Token（可选，提升API限流从60→5000次/小时）
DEEPSEEK_API_KEY: DeepSeek API Key（用于技能评测生成脚本、AI日报整理）

定时任务调度系统

后台管理: /admin/tasks（任务中心）、/admin/tasks/logs（执行日志）、/admin/tasks/[taskKey]（单任务详情+统计）
数据模型: TaskConfig（任务配置，含enabled/cronExpr/config）、TaskLog（执行历史，含status/duration/result/error）
种子数据: scripts/seed-task-configs.mjs 初始化6个任务配置
手动触发: /admin/tasks 页支持每个任务运行，也可通过 POST /api/admin/tasks/run 触发
API:
- GET/PUT /api/admin/tasks/configs — 任务配置查询/更新
- GET /api/admin/tasks/logs — 任务执行日志（分页+按taskKey筛选）
- POST /api/admin/tasks/run — 手动触发任务执行

定时任务（Crontab）

所有6个定时任务全部经过TaskLog记录：

时间	任务	脚本	TaskKey	说明
01:00	Task5 更新星值	`scripts/task5-update-stars.mjs`	task5-update-stars	更新所有GitHub技能Stars数+日/周/月变化
03:00	Task3 工具巡检	`scripts/task3-check-tools.mjs`	task3-check-tools	检查网站/Lo4go可访问性+自动发布合格待审核工具
04:00	Task6 评测热门	`scripts/task6-review-hot.mjs`	task6-review-hot	评测2个最热未评测GitHub技能(五维评测)
05:00	Task4 发现技能	`scripts/daily-discover.mjs`	task4-discover-skills	GitHub搜索≥1000 stars项目→DeepSeek预评测→入库PendingSkill
06:00	Task1 发现工具	`scripts/task1-discover-tools.mjs`	task1-discover-tools	36kr/IT之家/开源中国RSS→DeepSeek提取工具→入库PendingTool
07:30	AI日报	`scripts/daily-news.mjs`	daily-news	多源搜索真实新闻+DeepSeek整理格式→发布日报

Crontab 位于服务器: crontab -l（ubuntu用户）
日志目录: /home/ubuntu/zhuiguang-ai/logs/（task1.log ~ task6.log）

AI日报新闻源

36kr RSS (https://36kr.com/feed) — 国内科技资讯
IT之家 RSS (https://www.ithome.com/rss/) — 国内科技资讯
开源中国 RSS (https://www.oschina.net/news/rss) — 开源动态
HackerNews API — 海外AI/技术热点
Google News RSS — 海外新闻（国内服务器可能无法访问）
流程: 搜索真实新闻 → AI关键词过滤 → 近2天筛选 → DeepSeek整理格式 → 入库发布
严禁让DeepSeek直接生成新闻内容（会编造假新闻），必须基于真实新闻素材整理

踩坑记录

Next.js 14不支持useActionState，登录页用原生表单POST
Prisma MariaDB adapter需要连接字符串方式初始化
图片域名需在next.config.mjs中配置remotePatterns
热重载后需清除.next缓存: 删除.next目录后重启
Chart.js组件需用dynamic import + ssr: false，不支持服务端渲染
Prisma 7.8需通过PrismaMariaDb适配器初始化，不能直接new PrismaClient()
服务器环境SSL证书问题: 运行脚本需设置$env:NODE_TLS_REJECT_UNAUTHORIZED="0"

6. 安全原则

敏感信息（密钥、密码、Token）必须使用环境变量，禁止硬编码
.env 文件已被加入 .gitignore，仅 .env.example 模板可提交
HTTP 响应必须包含安全头：CSP、HSTS、X-Content-Type-Options、X-Frame-Options
文件上传/下载必须限制大小（最大 5MB）和类型，SVG 内容需消毒 script/iframe/on-event 标签
Logo 文件名使用 SHA256 哈希（不使用 MD5）
VIP 用户不能访问管理后台（/admin/* 和 /api/admin/*）

7. 可靠性原则

所有外部 API 调用（GitHub、DeepSeek 等）必须设置超时和重试
OpenAI/DeepSeek 客户端配置：timeout: 120000, maxRetries: 2
Octokit 配置：request.timeout: 30000，配合 withRetry 指数退避重试
定时脚本启动时必须验证必需环境变量（DEEPSEEK_API_KEY、DATABASE_URL）
DeepSeek 模型名使用环境变量 DEEPSEEK_MODEL（默认 deepseek-v4-pro）
OAuth 用户创建需处理 P2002 唯一约束冲突竞态

12 KiB Raw Blame History Unescape Escape

追光AI 项目开发规则

端口规范

服务器与基础设施

技术栈

代码风格

构建与检查

数据库

认证

API约定

页面路由

五大操作指令

探索AI工具

检测AI工具

探索AI技能

更新Skill技能

AI新闻发现

通用执行规则

设计系统

环境变量

定时任务调度系统

定时任务（Crontab）

AI日报新闻源

踩坑记录

6. 安全原则

7. 可靠性原则

12 KiB

Raw Blame History