Cosmos-Server 项目开发环境搭建指南

项目概述

Cosmos-Server 是一个基于现代技术栈构建的服务端项目，采用了前后端分离的架构设计。前端使用React框架构建，通过Vite进行打包；后端采用Go语言开发；整体项目依赖Docker容器化技术。本文将详细介绍如何搭建完整的本地开发环境。

开发环境准备

基础工具安装

开发Cosmos-Server需要安装以下核心工具：

1. Docker：容器化运行环境

   curl -fsSL https://get.docker.com | sudo sh
   

2. Node.js V16：前端开发环境

   • 必须使用V16版本以保证兼容性

3. Go语言 v1.21.6：后端开发环境

   • 需要精确匹配此版本以避免潜在问题

额外依赖文件

除了基础工具外，还需要准备以下资源文件：

1. GeoLite2-Country数据库（可选）

   • 用于测试地理位置功能
   • 需要从MaxMind官网获取

2. Nebula二进制文件

   • 需要下载两个架构版本：
     • AMD64架构版本
     • ARM64架构版本
   • 这些文件需要放置在项目根目录下

前端开发环境配置

初始化步骤

1. 安装依赖：

   npm install
   

2. 启动开发服务器：

   npm run client
   

   • 开发服务器默认运行在5173端口
   • 支持热重载功能

生产构建

完成开发后，可执行构建命令：

npm run client-build

• 生成优化后的静态资源文件
• 构建结果会自动用于后端集成

后端开发环境配置

构建与运行

1. 构建后端服务：

   npm run build
   

   • 生成的可执行文件位于build/目录
   • 会自动包含前端构建结果

2. 启动开发服务器：

   npm run start
   

   • 默认使用8443端口
   • 关键环境变量：
     • COSMOS_CONFIG_FOLDER=./zz_test_config：指定配置目录
     • CONFIG_FILE=./config_dev.json：指定开发配置文件

开发建议配置

为了获得最佳开发体验，建议采用以下配置：

1. 启用HTTPS自签名证书
   • 更接近生产环境行为
2. 使用外部数据库
   • 推荐Mongo Atlas免费版
   • 避免测试数据丢失
3. 启用Docker支持
4. 设置日志级别为DEBUG
5. 关闭监控功能减少干扰日志

Docker镜像构建与测试

开发镜像构建

1. 仅构建镜像：

   npm run dockerdevbuild
   

2. 构建并运行：

   npm run dockerdev
   

   • 使用dockerfile.local而非生产环境的Dockerfile
   • 包含开发工具和调试支持

演示系统

项目集成了模拟API调用的演示系统：

1. 启动演示开发服务器：

   npm run devdemo
   

2. 构建演示版本：

   npm run demo
   

分支管理策略

项目采用以下分支策略：

1. master分支：稳定版本
   • 仅接受热修复(hotfix)提交
2. unstable分支：开发测试版本
   • 接受新功能开发
   • 所有PR应基于目标分支创建

开发协作建议

1. 在实施重大变更前与团队充分沟通
2. 保持PR简洁单一
3. 复杂功能应拆分为多个PR
4. 遵循项目代码风格和架构设计

通过以上步骤，开发者可以建立完整的Cosmos-Server本地开发环境，参与项目功能开发和问题修复。建议初次接触项目的开发者先从简单的功能或问题入手，逐步熟悉项目架构和开发流程。