draadnl/openstad-api

openstad-api

镜像概述和主要用途

openstad-api是Openstad平台的后端API服务，主要用于处理客户端请求、管理数据库交互、实现用户身份验证与授权、配置邮件服务等核心功能。作为Openstad生态的重要组成部分，它为基于Openstad平台构建的应用提供稳定的后端支持。

核心功能和特性

• 数据库集成：支持多种数据库方言，可配置数据库连接参数（用户、密码、主机、数据库名等）
• 身份验证与授权：基于JWT的身份验证机制，支持与认证服务器集成，包含固定令牌配置
• 邮件服务：支持SMTP邮件发送配置，可自定义发件人地址和SMTP服务器参数
• 安全会话管理：提供安全的会话管理，支持会话密钥配置和仅安全连接设置
• 多环境支持：通过本地配置文件和环境变量实现多环境部署适配
• 测试支持：提供单元测试和端到端测试脚本

使用场景和适用范围

适用于需要构建基于Openstad平台的Web应用，尤其适合需要以下功能的场景：

• 需要后端API支持的用户认证与授权系统
• 需与数据库交互的Web应用
• 需要邮件通知功能的应用
• 需进行单元测试和端到端测试的开发环境

使用方法和配置说明

1. 安装

bash
git clone git@github.com:Amsterdam/openstad-api.git
cd openstad-api
npm install

2. 创建本地配置文件 ./config/local.js

创建配置文件并根据实际环境修改以下参数：

javascript
module.exports = {
  "url": "应用URL",
  "hostname": "域名",

  "database": {
    "user": "数据库用户名",
    "password": "数据库密码",
    "database": "数据库名",
    "host": "数据库主机",
    "dialect": "数据库方言（如mysql、postgres等）",
    "multipleStatements": true  // 是否允许多语句查询
  },

  "express": {
    "port": 端口号  // API服务监听端口
  },

  "mail": {
    "from": "发件人邮箱地址",
    "transport": {
      "smtp": {
        "port": SMTP端口,
        "host": "SMTP服务器地址",
        "auth": {
          "user": "SMTP用户名",
          "pass": "SMTP密码"
        }
      }
    }
  },

  "security": {
    "sessions": {
      "secret": "Cookie密钥",
      "onlySecure": true  // 是否仅在安全连接下使用
    }
  },

  "authorization": {
    "jwt-secret": "JWT签名密钥",
    "auth-server-url": "认证服务器URL",
    "auth-client-id": "认证客户端ID",
    "auth-client-secret": "认证客户端密钥",
    "auth-server-login-path": "/dialog/authorize?redirect_uri=[[redirectUrl]]&response_type=code&client_id=[[clientId]]&scope=offline",
    "auth-server-exchange-code-path": "/oauth/token",
    "auth-server-get-user-path": "/api/userinfo?client_id=[[clientId]]",
    "auth-server-logout-path": "/logout?clientId=[[clientId]]",
    "after-login-redirect-uri": "/?jwt=[[jwt]]",
    "fixed-auth-tokens": [  // 固定令牌配置
      {
        "token": "12345",  // 令牌值
        "userId": "2"      // 关联用户ID
      }
    ]
  }
}

3. 初始化数据库

执行数据库重置前，需确保以下环境变量已正确设置：

bash
# 前端URL
FRONTEND_URL=
# 认证服务URL
AUTH_URL=
# 认证客户端密钥（唯一哈希）
AUTH_FIRST_CLIENT_SECRET=
# 认证客户端ID（唯一哈希）
AUTH_FIRST_CLIENT_ID=
# 管理端URL（如 http://localhost:4444 或 https://admin.openstad.demo）
ADMIN_URL=
# 可选：内部认证服务器URL
AUTH_INTERNAL_SERVER_URL=

设置环境变量后执行数据库重置命令：

bash
env FRONTEND_URL=... AUTH_URL=... ... node reset.js

4. 启动服务器

bash
node server.js

5. 运行测试

提供以下测试脚本：

1. 运行所有测试场景

   bash
   npm run test
   

2. 仅运行单元测试

   bash
   npm run test:unit
   

3. 仅运行端到端测试

   bash
   npm run test:e2e
   

更多文档

更多详细信息请查看 docs目录。