ugentlib/biblio-backoffice

biblio-backoffice

镜像概述和主要用途

biblio-backoffice是根特大学学术文献系统Biblio的后台管理应用，提供对学术文献数据的管理和维护功能。该应用包含三个核心组件：服务于Web UI的Web服务器（供图书馆员和研究人员使用）、gRPC服务器以及gRPC CLI客户端（供系统管理员和数据管理员进行数据管理）。

核心功能和特性

• Web服务器：提供Web UI界面，支持图书馆员和研究人员访问和管理学术文献数据
• gRPC服务器：提供高性能远程过程调用服务，支持数据管理操作
• gRPC CLI客户端：允许数据管理员和系统管理员通过命令行远程管理数据
• 依赖外部数据存储和认证服务，确保数据安全和可靠存储

前提条件

应用需依赖以下外部服务和资源：

• PostgreSQL数据库（数据存储）
• ElasticSearch索引（搜索和索引功能）
• OpenID Connect端点（如Keycloak，用户认证）
• 磁盘存储（文件存储）

使用场景和适用范围

• 图书馆员和研究人员：通过Web UI访问和管理学术文献数据
• 系统管理员：通过gRPC服务器配置和维护系统
• 数据管理员：使用gRPC CLI客户端远程管理和维护数据

详细使用方法和配置说明

Web UI快速启动

手动部署

bash
git clone git@github.com:ugent-library/biblio-backoffice.git
go run main.go

或构建二进制文件：

bash
git clone git@github.com:ugent-library/biblio-backoffice.git
cd biblio-backoffice
go build -o /tmp/biblio-backoffice
./tmp/biblio-backoffice
# 或交叉编译，例如：
GOOS=linux GOARCH=amd64 go build -o /tmp/biblio-backoffice.linux.amd64

启动Web UI服务器：

bash
go run main.go start server

若无法连接PostgreSQL、ElasticSearch或OpenID Connect端点，服务器将报错退出。配置方法参见下文“配置说明”。

Docker部署

bash
docker run --name some-backoffice -d ugentlib/biblio-backoffice:dev

建议使用docker-compose管理端口、卷、环境变量等参数。

gRPC服务器与客户端

服务器

gRPC协议需要TLS支持，当前服务器未内置TLS，需通过代理（如Traefik v2，支持Let's Encrypt）提供TLS并转发流量。gRPC服务器应直接运行在独立域名的根路径下（而非子路径），例如grpc.myapplication.tld。

启动gRPC服务器：

bash
go run main.go api start
# 或
./tmp/biblio-backoffice api start

若无法连接PostgreSQL、ElasticSearch或OpenID Connect端点，服务器将报错退出。配置方法参见下文“配置说明”。

客户端

bash
git clone git@github.com:ugent-library/biblio-backoffice.git
cd biblio-backoffice/client
go run main.go --host <grpc.host.tld> --port <port> --username <username> --password <password>

或构建可分发的二进制文件：

bash
git clone git@github.com:ugent-library/biblio-backoffice.git
cd biblio-backoffice
go build -o /tmp/biblio-backoffice-client client/main.go
./tmp/biblio-backoffice-client
# 或交叉编译，例如：
GOOS=linux GOARCH=amd64 go build -o /tmp/biblio-backoffice-client.linux.amd64 client/main.go

gRPC客户端可在任何机器（如数据管理员的本地机器）上使用，支持通过凭据远程管理数据，无需与gRPC服务器在同一台机器。

配置说明

配置可通过参数或环境变量传递：

通过参数传递：

bash
go run main.go server start --session-secret mysecret

通过环境变量传递：

bash
BIBLIO_BACKOFFICE_SESSION_SECRET=mysecret go run main.go server start

必须设置的环境变量

bash
BIBLIO_BACKOFFICE_BASE_URL               # 应用基础URL
BIBLIO_BACKOFFICE_SESSION_SECRET         # 会话密钥
BIBLIO_BACKOFFICE_FILE_DIR               # 文件存储目录
BIBLIO_BACKOFFICE_FRONTEND_URL           # 前端URL
BIBLIO_BACKOFFICE_FRONTEND_USERNAME      # 前端用户名
BIBLIO_BACKOFFICE_FRONTEND_PASSWORD      # 前端密码
BIBLIO_BACKOFFICE_OIDC_URL               # OpenID Connect端点URL
BIBLIO_BACKOFFICE_OIDC_CLIENT_ID         # OpenID Connect客户端ID
BIBLIO_BACKOFFICE_OIDC_CLIENT_SECRET     # OpenID Connect客户端密钥
BIBLIO_BACKOFFICE_CSRF_NAME              # CSRF名称
BIBLIO_BACKOFFICE_CSRF_SECRET            # CSRF密钥
BIBLIO_BACKOFFICE_ORCID_CLIENT_ID        # ORCID客户端ID
BIBLIO_BACKOFFICE_ORCID_CLIENT_SECRET    # ORCID客户端密钥
BIBLIO_BACKOFFICE_ORCID_SANDBOX          # ORCID沙盒模式（布尔值）
BIBLIO_BACKOFFICE_PG_CONN                # PostgreSQL连接字符串（例如：postgres://localhost:5432/biblio_backoffice?sslmode=disable）
BIBLIO_BACKOFFICE_PUBLICATION_INDEX      # 出版物索引名（例如：biblio_backoffice_publications）
BIBLIO_BACKOFFICE_DATASET_INDEX          # 数据集索引名（例如：biblio_backoffice_datasets）
BIBLIO_BACKOFFICE_ES6_URL                # ElasticSearch URL（例如：http://localhost:9200）
BIBLIO_BACKOFFICE_MONGODB_URL            # MongoDB连接URL（例如：mongodb://localhost:27017/?directConnection=true&serverSelectionTimeoutMS=2000）
BIBLIO_BACKOFFICE_FRONTEND_ES6_URL       # 前端ElasticSearch URL（默认：http://localhost:9200）

可选环境变量

bash
BIBLIO_BACKOFFICE_MODE                   # 运行模式（默认：production）
BIBLIO_BACKOFFICE_PORT                   # 端口（默认：3000）
BIBLIO_BACKOFFICE_HOST                   # 主机（默认：localhost）
BIBLIO_BACKOFFICE_SESSION_NAME           # 会话名称（默认：biblio-backoffice）
BIBLIO_BACKOFFICE_SESSION_MAX_AGE        # 会话最大存活时间（默认：86400 * 30 // 30天）
BIBLIO_BACKOFFICE_HDL_SRV_ENABLED        # 句柄服务启用状态（默认：false）
BIBLIO_BACKOFFICE_HDL_SRV_URL            # 句柄服务URL（例如：http://localhost:4000/handles）
BIBLIO_BACKOFFICE_HDL_SRV_PREFIX         # 句柄服务前缀（例如：1854）
BIBLIO_BACKOFFICE_HDL_SRV_USERNAME       # 句柄服务用户名
BIBLIO_BACKOFFICE_HDL_SRV_PASSWORD       # 句柄服务密码
BIBLIO_BACKOFFICE_OAI_API_URL            # OAI API URL
BIBLIO_BACKOFFICE_OAI_API_KEY            # OAI API密钥
BIBLIO_BACKOFFICE_TIMEZONE               # 时区（默认：Europe/Brussels）

gRPC服务器特定环境变量

bash
BIBLIO_BACKOFFICE_HOST                   # 主机
BIBLIO_BACKOFFICE_PORT                   # 端口
BIBLIO_BACKOFFICE_ADMIN_USERNAME         # 管理员用户名
BIBLIO_BACKOFFICE_ADMIN_PASSWORD         # 管理员密码
BIBLIO_BACKOFFICE_CURATOR_USERNAME       # 数据管理员用户名
BIBLIO_BACKOFFICE_CURATOR_PASSWORD       # 数据管理员密码
BIBLIO_BACKOFFICE_INSECURE               # 不安全模式（默认：false）
BIBLIO_BACKOFFICE_TIMEOUT                # 超时时间（默认：5s）

gRPC客户端特定环境变量

bash
BIBLIO_BACKOFFICE_HOST                   # 服务器主机
BIBLIO_BACKOFFICE_PORT                   # 服务器端口
BIBLIO_BACKOFFICE_USERNAME               # 客户端用户名
BIBLIO_BACKOFFICE_PASSWORD               # 客户端密码
BIBLIO_BACKOFFICE_INSECURE               # 不安全模式（默认：false）

开发指南

开发环境搭建

本项目使用https://github.com/bokwoon95/wgo%E7%9B%91%E5%90%AC%E6%96%87%E4%BB%B6%E5%8F%98%E5%8C%96%E5%B9%B6%E8%87%AA%E5%8A%A8%E9%87%8D%E6%96%B0%E7%BC%96%E8%AF%91%E5%BA%94%E7%94%A8%E5%92%8C%E8%B5%84%E6%BA%90%EF%BC%9A

bash
cd biblio-backoffice
make dev
# 或
npm run dev

运行测试

项目包含Cypress集成测试：

• 命令行运行测试：

bash
npm test

• 记录测试结果到Cypress Dashboard：
  1. 将cypress/cypress-record.sh.example复制为cypress/cypress-record.sh
  2. 替换文件中的记录密钥为Cypress的密钥
  3. 运行：

bash
./cypress/cypress-record.sh

• GUI模式运行测试：

bash
npm run cypress:open

SASS/SCSS及资源编译

安装Node依赖：

bash
npm install

使用wgo时资源会自动重新编译（见上文“开发环境搭建”）。手动构建资源：

bash
node esbuild.mjs
# 或
npm run build:assets

详细参考https://esbuild.github.io/%E3%80%82

数据库迁移

bash
go install github.com/jackc/tern@latest
cd etc/pg/migrations
PGDATABASE=biblio_backoffice tern migrate

更多信息参见https://github.com/jackc/tern%E3%80%82PostgreSQL%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E8%AF%B4%E6%98%8E%E5%8F%82%E8%A7%81PostgreSQL%E6%96%87%E6%A1%A3%E3%80%82

开发容器

本项目支持开发容器，可快速搭建容器化开发环境。

安装开发容器扩展

1. 打开VS Code
2. 访问Dev Containers扩展页面
3. 点击“安装”按钮

配置开发容器

bash
cp .devcontainer.env.example .devcontainer.env

启动开发容器

1. 在VS Code中打开项目目录
2. 点击左下角绿色的“打开远程窗口”按钮
3. 从弹出菜单中选择“在容器中重新打开”
4. 成功打开后，左下角绿色按钮将显示“Dev Container: App name”
5. 从“终端”菜单打开新终端

运行项目

bash
make dev

应用启动后，VS Code会弹出链接，点击即可在浏览器中访问项目。

网络端口

应用及依赖服务运行端口如下：