makemd/docs/guides/server-readme.md

Crawlful Hub - Node.js 后端技术指南 (V30.0)

1. 技术栈

• Runtime: Node.js v20+
• Language: TypeScript (Strict Mode)
• Database: MySQL 8.0 (Aliyun RDS)
• Cache: Redis 6.0 (Local)
• ORM: Knex.js
• AI: Gemini-3-Flash, CLIP, Sentiment Analysis

2. 目录结构

• server/src/core/: AGI 内核、算力调度、隐私审计。
• server/src/domains/: 业务领域模型（Trade, Finance, Product, Logistics 等）。
• server/src/api/: 外部与内部 API 路由。
• server/src/workers/: 异步任务与爬虫任务。

3. 本地开发环境搭建

3.1 前置条件

# 安装 Node.js v20+
node -v  # 应显示 v20.x.x

# 安装 pnpm (推荐)
npm install -g pnpm

# 安装 MySQL 8.0 (本地或 Docker)
docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8.0

# 安装 Redis 6.0
docker run -d -p 6379:6379 redis:6.0

3.2 项目初始化

# 安装依赖
cd server
pnpm install

# 复制环境变量配置
cp .env.example .env
# 编辑 .env 配置数据库连接、Redis 等

# 运行数据库迁移
pnpm migrate:latest

# 启动开发服务器
pnpm dev

3.3 常用命令

命令	功能
pnpm dev	启动开发服务器 (热重载)
pnpm build	编译 TypeScript
pnpm start	生产环境启动
pnpm migrate:make	创建数据库迁移
pnpm seed:run	运行数据填充
pnpm lint	代码风格检查

3.4 调试指南

• VS Code 调试：配置 .vscode/launch.json 使用 Node.js debugger
• 日志级别：通过 LOG_LEVEL 环境变量控制 (debug/info/warn/error)
• API 测试：启动后访问 http://localhost:3000/api/health 检查服务状态

4. 代码规范

• 严格模式：tsconfig.json 启用 strict: true
• 路径别名：使用 @/* 引用 server/src 下的模块
• 命名规范：
  • 文件：小写短横线 (kebab-case)
  • 类/接口：大驼峰 (PascalCase)
  • 变量/函数：小驼峰 (camelCase)

5. 核心模块说明

• Core: AGI 决策引擎、算力调度、隐私计算
• Domains: 业务领域服务 (Trade/Finance/Product/Logistics)
• API: RESTful 接口层，含外部 API 与内部 API
• Workers: BullMQ 异步任务、Crawler 爬虫任务

---

版本记录: V30.0 (AI-Native Overhaul) 更新日志: [AI-3 @ 2026-03-15] 补充本地开发环境搭建与常用命令