toska/oodikone2-backend

oodikone2-backend

Master: ![Build Status]([***]

Trunk: ![Build Status]([***]

镜像概述和主要用途

oodikone2-backend是赫尔辛基大学计算机科学系Oodikone2系统的后端服务，主要用于处理学生数据、课程信息管理、教师排行榜统计及DEFA报告生成等功能。该服务基于Docker容器化部署，支持开发、测试和生产环境，集成PostgreSQL数据库和Redis缓存，提供稳定的数据处理和存储能力。

核心功能和特性

• 数据库集成：使用PostgreSQL存储学生、课程等核心数据，支持数据备份与恢复
• 缓存机制：通过Redis实现数据缓存，提升系统性能
• 学生数据更新：从WebOodi获取并更新学生信息，包括学生列表和详细信息
• 教师排行榜统计：计算并更新不同学年的教师排行榜数据
• DEFA报告生成：聚合DEFA学生数据，生成CSV格式报告
• 多环境支持：支持开发、测试、staging和生产环境部署
• 自动化部署：通过Travis CI实现镜像自动构建和推送

使用场景和适用范围

• 开发环境：开发人员本地构建和测试后端服务
• 测试环境：运行自动化测试，验证功能正确性
• 生产环境：部署到服务器，处理实际业务数据
• 数据管理：数据库备份、恢复及学生数据更新
• 统计分析：生成教师排行榜和DEFA报告

详细使用方法和配置说明

开发环境设置

前提条件

安装Docker CE和docker-compose：

• Docker CE：安装指南
• docker-compose：安装指南

创建docker-compose.yml

创建包含PostgreSQL和Redis的docker-compose配置文件：

yaml
version: '3'

services:
  db:
    image: postgres:9.6.3
    ports:
      - "5421:5432"
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    container_name: oodi_db
  redis:
    image: redis
    command: ["redis-server", "--appendonly", "yes"]
    ports:
      - "6379:6379"
    volumes:
      - ./redis-data:/data
    container_name: redis

启动服务

启动PostgreSQL和Redis容器：

bash
docker-compose up -d

数据库配置

1. 从服务器复制备份文件：

bash
scp oodikone.cs.helsinki.fi:/home/tkt_oodi/backups/2018-08-01.bak <本地目录>

2. 创建数据库：

bash
docker exec -u postgres oodi_db psql -c "CREATE DATABASE tkt_oodi"

3. 恢复数据：

bash
cat 2018-08-01.bak | docker exec -i oodi_db psql -U postgres -d tkt_oodi

4. 验证数据：

bash
docker exec -it -u postgres oodi_db psql -d tkt_oodi
\dt  # 查看表结构

5. 创建测试数据库：

bash
docker exec -u postgres oodi_db psql -c "CREATE DATABASE tkt_oodi_test"
cat test.bak | docker exec -i oodi_db psql -U postgres -d tkt_oodi_test

安装Node.js和项目依赖

1. 安装Node.js：下载地址

2. 克隆仓库并安装依赖：

bash
git clone git@github.com:UniversityOfHelsinkiCS/oodikone2-backend.git
cd oodikone2-backend
npm install

配置环境变量

创建.env文件：

DB_URL=postgres://postgres@localhost:5421/tkt_oodi
TEST_DB=postgres://postgres@localhost:5421/tkt_oodi_test
FRONT_URL=http://localhost:8000
REDIS=localhost
TOKEN_SECRET=IWannaBeTheVeryBest

初始化Redis

bash
npm run init_redis
npm run seed_redis

运行服务

开发模式

bash
npm run dev

测试模式

bash
npm test

部署流程

部署策略

• 始终先部署到staging环境
• 从trunk合并到master分支时，Travis自动构建并推送staging镜像
• 在master分支创建release或tag时，Travis自动构建并推送生产镜像

更新步骤

1. 登录服务器：

bash
ssh {用户名}@oodikone.cs.helsinki.fi

2. 切换用户：

bash
sudo su - tkt_oodi

3. 进入对应目录：

bash
cd oodikone.cs.helsinki.fi  # 生产环境
# 或
cd oodikone.cs.helsinki.fi/staging  # staging环境

4. 运行更新脚本：

bash
./update.sh

数据库恢复

当数据库出现问题时，可按以下步骤恢复：

1. 删除当前数据库：

bash
docker exec -u postgres oodi_db dropdb tkt_oodi

2. 从服务器复制备份文件（同开发环境设置步骤）

3. 重新创建数据库并恢复数据（同开发环境设置步骤）

访问生产/Staging数据库

直接访问

bash
# 生产环境
docker exec -it -u postgres db psql -d tkt_oodi

# Staging环境
docker exec -it -u postgres db_staging psql -d tkt_oodi_staging

备份信息

• 生产数据库每日自动备份，存储路径：/var/toska/tkt_oodi/backups/postgres/
• 最新备份符号链接：/home/tkt_oodi/backups/latest-pg.bak.bz2

手动创建备份

bash
docker exec -u postgres db pg_dump tkt_oodi > `date +%Y-%m-%d`.bak

数据更新器（Updater）

oodikone2-backend包含从WebOodi获取学生数据的更新脚本，分为学生列表更新器和学生信息更新器，生产和staging环境各有独立的更新器，分别位于/oodikone.cs.helsinki.fi/updater和/oodikone.cs.helsinki.fi/staging/updater目录，容器名称为production_updater和staging_updater（以下用CONTAINER_NAME指代）。

学生列表更新器

用于获取有效学生编号，在updater目录中通过_update_student_list.sh运行，在独立容器中后台执行，可通过graylog或debug.log查看进度。

• 环境变量：INCREMENT（控制从当前最大学生编号开始搜索的新编号数量，当前未设置）

• 保存学生编号到文本文件：

bash
docker-compose run -d CONTAINER_NAME node src/services/doo_api_database_updater/student_list_updater.js /updater_files/all_student_numbers.txt

学生信息更新器（数据库更新器）

用于更新数据库中的学生信息：

bash
# 基本用法
docker-compose run -d CONTAINER_NAME npm run update_database

# 可选参数：指定学生编号文件和起始行
docker-compose run -d CONTAINER_NAME npm run update_database file="<文件名>" index=<数字>

***数据与E2E环境

使用https://github.com/UniversityOfHelsinkiCS/oodikone2-cli%E8%AE%BE%E7%BD%AE%E7%8E%AF%E5%A2%83%EF%BC%9A

1. 为Anonyymioodi私有仓库创建部署密钥，保存为private.key放在cli目录中

2. 本地开发使用***数据：选择2) Anon setup（可运行E2E测试）

3. E2E测试：

bash
# 本地运行
npm run cypress:open

# 在ToskaWatch中运行
npm run cypress:run

教师排行榜统计

通过脚本单独计算教师排行榜统计数据：

bash
# 更新学年50（1999-20）到70（2018-19）的教师排名
docker-compose run -d CONTAINER_NAME npm run update_top_teachers from=50 to=70

# 更新单个学年的教师排名（省略to参数）
docker-compose run -d CONTAINER_NAME npm run update_top_teachers from=50

DEFA报告

create_defa_report npm脚本可快速聚合DEFA学生数据并生成CSV格式报告，仅在Oodikone生产服务器上运行有效。

输入文件

输入文件需放置在/home/tkt_oodi/oodikone.cs.helsinki.fi/defa目录（或后端容器中挂载为/usr/src/app/defa的目录）：

• params.json：定义输入/输出文件路径及时间范围

  json
  {
    "out": {
      "report": "/usr/src/app/defa/defa-report.csv",
      "stats": "/usr/src/app/defa/defa-stats.csv"
    },
    "in": {
      "course_ids": "/usr/src/app/defa/ids.txt",
      "included_courses": "/usr/src/app/defa/included.txt",
      "required_courses": "/usr/src/app/defa/required.txt",
      "timeframe": {
        "start": "2018-09-01T01:00:00.000Z",
        "end": "2019-06-30T01:00:00.000Z"
      }
    }
  }
  

• ids.txt：DEFA课程的courseunitrealisation ID列表

  126240934
  126237007
  126238082
  

• included.txt：需包含的课程learningopportunity ID列表（AY课程可省略AY前缀以匹配两种形式）

  TKT10002
  TKT10003
  MAT11001
  

• required.txt：DEFA学生必须完成的课程ID列表（需同时在included.txt中）

运行命令

bash
# 直接执行
docker exec <backend容器> npm run create_defa_report defa/<参数json文件>

# 使用现成脚本
/home/tkt_oodi/oodikone.cs.helsinki.fi/defa/create_report.sh

输出文件

• defa-report.csv：包含每个DEFA学生的详细信息及所有DEFA学生的汇总信息
• defa-stats.csv：包含DEFA学生的学分分布情况

旧输出文件会被覆盖，除非已重命名或移动。