在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

laurent22/joplin

菜单

服务器组件

相关源文件

目的与范围

本文档涵盖了 Joplin 生态系统的服务器端组件。Joplin 服务器为 Joplin 客户端提供同步服务、用户管理和订阅处理。它充当 Joplin Cloud 的骨干，也可以自行托管。本文档重点介绍了服务器架构、数据库连接、路由系统、用户管理和其他核心服务器功能。

有关连接到服务器的客户端应用程序的信息，请参阅 客户端应用程序。

来源： packages/server/src/app.ts1-383 packages/server/src/config.ts1-224

服务器架构概述

Joplin 服务器基于 Node.js，使用 Koa Web 框架构建。主要组件包括：

  1. 核心应用程序：初始化服务器、设置中间件和连接数据库的入口点
  2. 请求处理：通过中间件和路由处理传入的 HTTP 请求
  3. 数据模型：管理数据访问和业务逻辑
  4. 服务：提供模板和支付处理等功能

来源： packages/server/src/app.ts99-376 packages/server/src/middleware/routeHandler.ts1-98 packages/server/src/routes/routes.ts1-83

服务器初始化与配置

服务器的初始化始于 app.ts 文件，其中执行了以下操作：

  1. 加载和解析环境变量
  2. 设置数据库连接
  3. 配置中间件
  4. 初始化服务
  5. 开始监听请求

配置系统支持多种设置，包括：

  • 数据库配置：SQLite 或 PostgreSQL
  • API 端点：API、Web 界面和用户内容的基 URL
  • 邮件发送器设置：用于向用户发送电子邮件
  • Stripe 集成：用于处理订阅
  • 存储驱动：用于存储用户数据

来源： packages/server/src/app.ts99-376 packages/server/src/config.ts34-221 packages/server/src/env.ts12-286

数据库层

服务器支持两种数据库系统：SQLite（默认）和 PostgreSQL。数据库层提供：

  1. 连接管理：建立和管理数据库连接
  2. 迁移：处理模式更改和版本管理
  3. 查询实用程序：提供处理数据库查询的实用程序
  4. 事务支持：允许原子化数据库操作

数据库配置由环境变量决定，开发和生产环境有不同的设置。该系统支持数据库复制，采用主/从设置以实现高可用性。

来源： packages/server/src/db.ts34-512 packages/server/src/app.ts302-366 packages/server/src/config.ts47-84

路由系统

路由系统负责处理 HTTP 请求并将其定向到相应的处理程序。它支持三种类型的路由：

路由类型目的基础 URL
Web面向用户的 HTML 界面config().baseUrl
API面向客户端应用程序的 JSON 端点config().apiBaseUrl
UserContent内容托管（附件等）config().userContentBaseUrl

关键路由文件包括：

  • routes/api/：API 端点（JSON 响应）
  • routes/index/：Web UI 路由（HTML 响应）
  • routes/admin/：管理员界面路由

路由器解析 URL 以提取参数，并将其与相应的处理程序匹配，支持嵌套路由和参数化路径。

来源： packages/server/src/middleware/routeHandler.ts1-98 packages/server/src/utils/routeUtils.ts20-326 packages/server/src/routes/routes.ts1-83

用户管理和认证

The UserModel 处理与用户相关的操作：

  1. 身份验证：用户登录及密码验证
  2. 账户创建：创建新用户账户
  3. 电子邮件验证：发送和处理确认电子邮件
  4. 账户管理：更新用户详细信息和偏好设置
  5. 访问控制：处理权限和限制

用户账户有不同的类型，每种类型都有特定的能力：

账户类型共享文件大小限制总存储空间
默认是无限制无限制
基础仅接收10 MB1 GB
专业版完全共享200 MB10 GB

身份验证过程使用会话 cookie 进行 Web 访问，并使用 API 令牌进行客户端应用程序访问。密码安全包括哈希处理和密码强度验证。

来源： packages/server/src/models/UserModel.ts118-709 packages/server/src/routes/index/users.ts1-273 packages/server/src/routes/index/login.ts1-123

会话用于在请求之间进行用户身份验证。会话流程如下：

  1. 用户使用凭据登录
  2. 服务器验证凭据并创建会话
  3. 会话 ID 存储在 cookie 中
  4. 后续请求包含此 cookie
  5. 中间件验证会话并附加用户数据

会话模型实现了会话创建、验证和过期。可以通过注销或管理员操作终止会话。

来源： packages/server/src/models/SessionModel.ts1-107 packages/server/src/routes/index/login.ts1-123 packages/server/src/middleware/ownerHandler.ts

订阅和支付管理

Joplin Server 集成了 Stripe 用于订阅管理。这使得：

  1. 套餐选择：用户可以选择基础版或专业版套餐
  2. 支付处理：通过 Stripe 安全地处理支付
  3. 订阅管理：处理续订、取消和升级
  4. Webhook 处理：处理 Stripe 事件以进行订阅更改

关键订阅组件

  1. Stripe 路由：处理结账、Webhook 和客户门户
  2. 订阅模型：管理订阅数据和状态
  3. 账户类型：根据订阅级别控制功能
  4. 付款处理：处理成功和失败的付款

Beta 用户在需要订阅之前会获得一个试用期，并在 Beta 试用期临近结束时收到自动通知。

来源： packages/server/src/routes/index/stripe.ts1-597 packages/server/src/models/SubscriptionModel.ts1-226 packages/server/src/utils/stripe.ts1-201

视图和模板

服务器使用 Mustache 模板渲染 HTML 视图。模板系统由 MustacheService 管理

主要视图系统功能

  1. 布局：主要页面结构（default.mustache）
  2. 部分：可重用的模板组件
  3. 视图对象：结合模板和内容的结构化数据
  4. Markdown 支持：视图可以用 Markdown 编写并渲染为 HTML
  5. CSS 和 JS 资源：样式表和脚本管理

视图系统会自动处理导航、通知和账户信息等常用元素。

来源： packages/server/src/services/MustacheService.ts1-309 packages/server/src/middleware/routeHandler.ts17-90 packages/server/src/views/layouts/default.mustache1-53

变更管理与同步

Joplin 服务器的核心功能之一是管理跨设备同步的变更。变更系统

  1. 记录所有创建、更新和删除操作
  2. 提供增量 API 以实现高效同步
  3. 跟踪用户共享项目的变更

ChangeModel 管理这些操作，通过计数器跟踪变更，以确保客户端之间的正确排序和一致状态。

来源： packages/server/src/models/ChangeModel.ts1-1140 packages/server/src/routes/index/changes.ts

测试基础设施

服务器包含一个全面的测试框架来验证功能

主要测试组件

  1. 数据库设置：创建独立的测试数据库
  2. 上下文创建：模拟 HTTP 请求和 Koa 上下文
  3. 用户管理：创建测试用户和会话
  4. 断言：用于 API 测试的专用断言
  5. 清理：确保测试不会相互影响

测试基础结构支持单元测试和集成测试，可以对服务器功能进行全面验证。

来源： packages/server/src/utils/testing/testUtils.ts30-676 packages/server/src/routes/index/users.test.ts1-319 packages/server/src/models/UserModel.test.ts1-255

结论

Joplin 服务器提供了一个强大的平台，用于同步、用户管理和内容共享。其模块化架构允许灵活部署，同时在不同环境中保持一致的功能。理解这些服务器组件对于维护、扩展或部署 Joplin 同步服务器至关重要。