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 ***:ugent-library/biblio-backoffice.git
go run main.go

或构建二进制文件：

bash
git clone ***: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 ***: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 ***: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）

开发指南

开发环境搭建

本项目使用wgo监听文件变化并自动重新编译应用和资源：

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

详细参考esbuild文档。

数据库迁移

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

更多信息参见tern文档。PostgreSQL环境变量说明参见PostgreSQL文档。

开发容器

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

安装开发容器扩展

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会弹出链接，点击即可在浏览器中访问项目。

网络端口

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