murmurationlabs/bitscreen-backend

BitScreen API

镜像概述和主要用途

BitScreen API是BitScreen应用的后端服务，提供核心业务功能支持。该服务基于Node.js构建，集成PostgreSQL数据库，通过TypeORM进行数据访问层管理，支持开发环境和生产环境部署，可通过Docker或docker-compose快速搭建运行环境。

核心功能和特性

• 集成PostgreSQL数据库，支持数据持久化存储
• 通过TypeORM管理数据库schema，提供数据库同步、日志查询等功能
• 支持开发模式（使用nodemon实现热重载）和生产模式部署
• 提供Docker化部署方案，支持docker-compose一键启动服务及依赖组件
• 支持数据库种子数据填充，便于环境初始化

使用场景和适用范围

• 开发环境：快速搭建本地开发环境，进行API功能开发和测试
• 生产环境：部署至Kubernetes集群（如EKS），提供稳定的后端服务
• 测试环境：通过Docker容器化部署，确保测试环境一致性

详细使用方法和配置说明

环境准备

• Node.js环境（建议使用与项目兼容的版本）
• PostgreSQL数据库（可本地安装或通过Docker运行）
• Docker及docker-compose（如需容器化部署）

手动部署步骤（Ubuntu 20.04）

1. 克隆项目代码：

   bash
   git clone <项目仓库地址>
   

2. 切换至development分支：

   bash
   git checkout development
   

3. 安装依赖：

   bash
   yarn install
   

4. 配置数据库连接：

   • 复制ormconfig.json.example创建ormconfig.json：

     bash
     cp ormconfig.json.example ormconfig.json
     

   • 根据实际环境修改ormconfig.json中的数据库连接参数

5. 安装PostgreSQL：

   • 参考教程：如何在Ubuntu 20.04上安装和使用PostgreSQL

6. 配置PostgreSQL数据库：

   • 访问PostgreSQL：

     bash
     sudo -u postgres psql
     

   • 创建数据库：

     sql
     create database bitscreen;
     

   • 创建用户并设置密码：

     sql
     create user bitscreen with encrypted password 'bitscreen';
     

   • 授予用户数据库权限：

     sql
     grant all privileges on database bitscreen to bitscreen;
     

7. 同步数据库schema：

   bash
   yarn typeorm schema:sync
   

8. 初始化provider表数据：

   • 连接到bitscreen数据库：

     bash
     sudo -u postgres psql -d bitscreen
     

   • 插入初始化数据：

     sql
     INSERT INTO provider(created, updated, id, "walletAddressHashed", country, "businessName", website, email, "contactPerson", address) 
     VALUES('2021-07-16 10:23:54', '2021-07-16 10:24:54', '0', 'anonymous', 'anonymous', 'anonymous', 'anonymous', 'anonymous', 'anonymous', 'anonymous');
     

9. 启动服务：

   bash
   yarn start
   

使用TypeORM

• 查看所有可用命令：

  bash
  yarn typeorm
  

• 常用命令示例：
  • 同步数据库schema：yarn typeorm schema:sync
  • 查看schema变更日志：yarn typeorm schema:log
  • 执行自定义查询：yarn typeorm query [查询语句]

数据库种子数据填充

1. 修改package.json，移除"type": "module"
2. 修改tsconfig.json，设置"module": "CommonJS"
3. 执行配置和种子数据填充：

   bash
   yarn seed:config
   yarn seed:run
   

开发模式运行

• 使用yarn start启动服务（通过nodemon实现热重载）
• 快速迭代方式：
  • 仅使用Docker运行PostgreSQL（修改docker-compose.yml，注释bitscreen-api部分）或使用系统PostgreSQL
  • 在终端中运行yarn start启动服务
  • 首次运行及src/entity目录下schema变更后，需执行yarn schema:sync

Docker部署

使用docker-compose启动

docker-compose会同时启动PostgreSQL数据库和BitScreen服务：

bash
docker-compose up

默认使用Docker Hub上的murmurationlabs/bitscreen-backend:latest镜像。

构建本地镜像

bash
docker build -t murmurationlabs/bitscreen-backend:local .

（可使用不同标签避免覆盖latest标签）

连接Docker中的数据库

bash
psql -h localhost -p 5432 -d bitscreen -U bitscreen
# 输入密码：bitscreen
# 进入psql交互界面后可执行SQL命令

生产部署

• 主要部署在EKS（Amazon Elastic Kubernetes Service）
• 使用Docker Hub上的murmurationlabs/bitscreen-backend:latest镜像（master分支推送时自动更新）
• PostgreSQL数据库通过Bitnami Helm Chart部署

注意事项

• 所有Node.js命令需使用以下选项以支持TypeORM运行：--experimental-modules --es-module-specifier-resolution=node --loader ts-node/esm