开发

相关源文件

• .github/PULL_REQUEST_TEMPLATE.md
• .github/config/exclude.txt
• .github/workflows/auto-test.yml
• .github/workflows/close-incorrect-issue.yml
• .github/workflows/prevent-file-change.yml
• .github/workflows/stale-bot.yml
• CONTRIBUTING.md
• README.md
• SECURITY.md
• extra/check-lang-json.js
• extra/close-incorrect-issue.js

此页面为希望为Uptime Kuma做出贡献的开发者提供了指导。它涵盖了开发环境的设置、项目结构的理解、开发工作流程、测试流程以及贡献指南。

设置开发环境

在您开始为Uptime Kuma做出贡献之前，您需要设置好您的开发环境。

要求

• 平台：主流Linux发行版、Windows 10 (x64) 或更高版本，或macOS
• 工具:
  • Node.js >= 18 / 20.4
  • npm >= 9
  • Git
  • 支持ESLint和EditorConfig的IDE
  • (可选) SQLite GUI工具

来源： CONTRIBUTING.md477-487 README.md61-70

为开发安装

1. 克隆仓库

2. 安装依赖项

3. 启动开发服务器

   此命令将同时启动前端开发服务器（端口3000）和后端开发服务器（端口3001）。

   如果您只需要重新启动服务器而不重新启动前端，可以在单独的终端中运行以下命令

来源： CONTRIBUTING.md496-520 README.md73-76

项目结构

Uptime Kuma遵循特定的目录结构。理解此结构对于有效开发至关重要。

目录组织

来源： CONTRIBUTING.md17-29

服务器结构

后端是一个集成了Socket.io的Express.js服务器。它使用Socket.io与客户端通信，大部分服务器逻辑封装在Socket.io处理程序中。

来源： CONTRIBUTING.md524-546

前端结构

前端是一个Vue.js单页应用程序（SPA）。大部分路径由Vue Router处理，数据存储在根级别。

来源： CONTRIBUTING.md562-573

开发工作流

了解Uptime Kuma的开发工作流程将有助于您有效地贡献。

Git 分支

• master： 2.X.X 开发分支。在此基础上进行新功能的拉取请求。
• 1.23.X： 1.23.X 开发分支。在此基础上进行适用于v1和v2的bug修复拉取请求。

来源： CONTRIBUTING.md489-494

开发流程工作流

来源： CONTRIBUTING.md224-312 CONTRIBUTING.md359-384

构建与测试

构建前端

为生产环境构建前端

这将把前端编译到dist目录，服务器将服务这些静态文件。

来源： CONTRIBUTING.md557-561

运行测试

Uptime Kuma使用各种测试方法来确保代码质量

来源： .github/workflows/auto-test.yml37-43 .github/workflows/auto-test.yml74-77 CONTRIBUTING.md578-583

测试工作流程

来源： .github/workflows/auto-test.yml22-26 .github/workflows/auto-test.yml36-43

贡献指南

拉取请求流程

1. Fork该存储库并创建一个新分支用于您的功能或bug修复。
2. 对于重大更改，请创建一个空提交以开始讨论

3. 进行更改，遵循编码标准。
4. 彻底测试您的更改。
5. 创建带有清晰描述的草稿拉取请求。
6. 完成PR清单中的所有项目。
7. 处理审阅者的反馈。
8. 完成后，将您的PR标记为“准备好审阅”。

来源： CONTRIBUTING.md359-440 .github/PULL_REQUEST_TEMPLATE.md39-54

代码风格指南

Uptime Kuma遵循特定的编码标准

• 缩进： 4个空格
• 遵循.editorconfig设置
• 遵循ESLint规则
• 使用JSDoc记录方法和函数

命名约定

• JavaScript/TypeScript： camelCaseType
• SQLite： snake_case (下划线)
• CSS/SCSS： kebab-case (破折号)

来源： CONTRIBUTING.md464-476

贡献类型

Uptime Kuma接受不同类型的贡献，每种都有特定的指南

贡献类型	指南	审批流程
小型Bug修复	保持PR小巧，一次修复一件事，彻底测试	初级维护者可以合并
翻译	使用Weblate进行翻译，除非是添加新的语言键	初级维护者可以合并
新的通知提供程序	实现前端和后端组件，测试所有通知事件	初级维护者可以合并
新的监控类型	实现监控类型，更新UI，包含翻译	初级维护者可以合并
新功能 / 重大更改	先创建草稿PR或issue进行讨论	只有高级维护者才能合并

来源： CONTRIBUTING.md30-220 CONTRIBUTING.md316-349

Docker 开发

Uptime Kuma为开发和部署提供了Docker支持。

Docker 架构

Uptime Kuma Docker镜像支持以下架构

• amd64
• arm64
• armv7

来源： CONTRIBUTING.md638-643

Docker 标签

对于版本2

• 2，latest-2：v2完整功能版
• 2-slim：v2基础功能版
• beta2：最新测试版
• nightly2：开发版
• base2：基础Debian设置

对于版本1

• 1，latest，debian：v1最新版本
• beta：最新测试版
• nightly：开发版

来源： CONTRIBUTING.md645-671

Docker 开发工作流程

来源： CONTRIBUTING.md692-723

安全考量

在为 Uptime Kuma 开发时，安全应是首要任务

• 请勿公开报告安全问题；请使用 GitHub 安全公告
• 请遵循 SECURITY.md 中的安全策略。
• 彻底测试安全修复
• 在所有更改中考虑潜在的安全影响

来源： SECURITY.md1-22 CONTRIBUTING.md42-57

维护和发布流程

Uptime Kuma 有特定的维护和发布流程

发布流程

对于正式发布

1. 草拟发布说明
2. 使用环境变量运行 npm run release-final
3. 推送到 GitHub
4. 发布版本。
5. 部署到演示服务器

对于 Beta 发布

1. 草拟预发布说明
2. 使用环境变量运行 npm run release-beta
3. 发布 Beta 版本

来源： CONTRIBUTING.md727-763

故障排除开发问题

常见问题

1. Socket.io 连接问题:

   • 检查前端和后端服务器是否都在运行
   • 如果使用 Docker，请验证端口映射
   • 如果前端和后端运行在不同的域上，请检查 CORS 问题

2. 数据库迁移错误:

   • 检查 db/knex_migrations/ 中的迁移脚本
   • 验证数据库的完整性

3. 构建错误:

   • 确保 Node.js 版本兼容（18 或 20.4）
   • 运行 npm ci 而不是 npm install 以进行干净的依赖安装

来源： CONTRIBUTING.md574-577 README.md67-69

其他资源

• 贡献指南
• Wiki 仓库
• 有关测试拉取请求的信息，请参阅 测试拉取请求
• 有关实用程序和助手的信息，请参阅 实用程序和助手

来源： CONTRIBUTING.md632-635