n8n CLI 项目结构全面分析
📁 项目概览
这是 n8n 的核心 CLI 包，基于 TypeScript + Express 构建的工作流自动化工具后端服务。
🗂️ 核心目录结构
E:\source\m-n8n-1125\packages\cli
├── bin/ # 可执行文件入口
│ └── n8n # CLI 启动脚本
├── src/ # 源代码目录
│ ├── controllers/ # 🔥 REST API 控制器（接口开发核心）
│ ├── services/ # 业务逻辑服务层
│ ├── commands/ # CLI 命令实现
│ ├── databases/ # 数据库相关
│ ├── auth/ # 认证授权
│ ├── webhooks/ # Webhook 处理
│ ├── workflows/ # 工作流执行
│ ├── credentials/ # 凭证管理
│ ├── executions/ # 执行记录
│ ├── middlewares/ # Express 中间件
│ ├── server.ts # 主服务器启动文件
│ └── abstract-server.ts # 服务器抽象基类
├── dist/ # 编译输出目录
├── test/ # 测试文件
└── templates/ # 模板文件
🎯 在哪里开发接口？
1️⃣ Controllers 目录 - 接口开发的核心位置
路径: src/controllers/ 所有 REST API 接口都在这里定义。主要控制器包括：
控制器文件 功能说明 路由前缀
users.controller.ts 用户管理 /users
workflows.controller.ts 工作流管理 /workflows
auth.controller.ts 认证登录 /auth
executions.controller.ts 执行记录 /executions
credentials.controller.ts 凭证管理 /credentials
project.controller.ts 项目管理 /projects
ai.controller.ts AI 功能 /ai
📝 控制器示例结构（users.controller.ts:50）
@RestController('/users') // 路由装饰器
export class UsersController {
constructor(
private readonly userService: UserService,
private readonly authService: AuthService,
// ... 依赖注入
) {}
@Get() // GET 请求装饰器
async list(@Query() filters: UsersListFilterDto) {
// 接口逻辑
}
@Patch('/:id') // PATCH 请求装饰器
async update(@Param('id') id: string, @Body() data: UpdateDto) {
// 更新逻辑
}
}
2️⃣ Services 目录 - 业务逻辑层
路径: src/services/ 服务层包含具体的业务实现：
user.service.ts - 用户业务逻辑
workflow.service.ts - 工作流业务逻辑
ai.service.ts - AI 服务
project.service.ee.ts - 项目服务（企业版）
credentials.service.ts - 凭证服务
🏗️ 整体框架架构
核心技术栈
Express.js # Web 框架
TypeScript # 编程语言
TypeORM # ORM 数据库操作
@n8n/decorators # 装饰器（路由、依赖注入）
@n8n/di # 依赖注入容器
class-validator # 数据验证
helmet # 安全中间件
架构分层
┌─────────────────────────────────────┐
│ Controllers（控制器层） │ ← REST API 接口定义
│ @RestController, @Get, @Post... │
├─────────────────────────────────────┤
│ Services（服务层） │ ← 业务逻辑实现
│ UserService, WorkflowService... │
├─────────────────────────────────────┤
│ Repositories（数据访问层） │ ← 数据库操作
│ UserRepository, WorkflowRepo... │
├─────────────────────────────────────┤
│ Database（数据库） │ ← SQLite/Postgres/MySQL
│ TypeORM │
└─────────────────────────────────────┘
启动流程
入口: bin/n8n
检查 Node.js 版本
加载环境变量（dotenv）
加载配置文件
命令注册: CommandRegistry.execute()
注册所有 CLI 命令（start, worker, webhook 等）
服务启动: server.ts:90 Server.start()
初始化 Express 应用
加载所有控制器（33-64 行导入）
设置中间件（cors, compression, helmet）
启动 HTTP/HTTPS 服务器
控制器注册: server.ts:33-64
import '@/controllers/users.controller';
import '@/controllers/workflows.controller';
// ... 所有控制器自动注册
🔑 开发接口的步骤
示例：添加一个新的用户统计接口
在 Controllers 创建接口
// src/controllers/users.controller.ts
@Get('/statistics')
@GlobalScope('user:read')
async getStatistics(@Req() req: AuthenticatedRequest) {
return await this.userService.getStatistics();
}
在 Services 实现业务逻辑
// src/services/user.service.ts
async getStatistics() {
const totalUsers = await this.userRepository.count();
const activeUsers = await this.userRepository.countActiveUsers();
return { totalUsers, activeUsers };
}
在 Repositories 添加数据查询（如需要）
// @n8n/db 包中的 UserRepository
async countActiveUsers() {
return this.count({ where: { disabled: false } });
}
📦 关键依赖包
@n8n/db - 数据库层（TypeORM entities, repositories）
@n8n/decorators - 装饰器（@RestController, @Get, @Post）
@n8n/di - 依赖注入容器
@n8n/api-types - API 类型定义和 DTO
@n8n/config - 配置管理
n8n-workflow - 工作流核心逻辑
n8n-core - 核心功能
🔧 开发命令
pnpm run dev - 启动开发模式（TypeScript 监听 + Nodemon 自动重启）
pnpm run build - 编译 TypeScript
pnpm run test - 运行测试
pnpm run watch - 仅监听编译（不启动服务）
📚 学习建议
从 Controllers 入手 - 先看 users.controller.ts 理解接口定义方式
研究 Services - 看 user.service.ts 学习业务逻辑
理解装饰器 - 查看 @n8n/decorators 包了解 @RestController、@Get、@Post 等装饰器用法
查看启动流程 - 阅读 server.ts 理解服务初始化
研究中间件 - 看 middlewares/ 了解请求处理流程
这是一个典型的企业级 Node.js 后端项目，采用了依赖注入、装饰器等现代化开发模式！