nypl/circ-scripts

Library Simplified 流通管理器

SimplyE应用将于2025年8月停用，此处共享的资源也将被移除。

!https://github.com/nypl-simplified/circulation/actions/workflows/test.yml/badge.svg?branch=develop !GitHub发布

目录

• 概述
• Git分支工作流
• 开发
  • 安装
  • 操作
  • 测试
  • 代码变更
  • 在流通管理器管理界面添加馆藏
• 生成文档
• 持续集成
• 使用NewRelic运行
• 贡献
• 许可
• 附录

概述

这是Library Simplified的流通管理器。流通管理器是图书馆馆藏与Library Simplified各种客户端应用（包括SimplyE）之间的主要连接纽带。它处理用户认证，将授权作品与开放获取内容相结合，从发行商API和次要来源获取更新的图书信息，并以适当组织的OPDS订阅源形式提供可用图书。

Git分支工作流

默认分支为develop，这是用于分支开发 bug 修复或新功能的工作分支。功能分支的拉取请求合并到develop后，可将更改合并到main以创建发布版本。

名称遵循<organization>-deploy-<env>模式的分支受保护，用作指定组织CI/CD流程的一部分。这些分支包括：

• nypl-deploy-qa
• nypl-deploy-production
• openebooks-deploy-qa
• openebooks-deploy-production
• bpl-deploy-qa
• bpl-deploy-production

开发

运行流通管理器实例的首选方法是通过Docker容器。如果因某种原因无法运行容器化版本，直接安装的初始说明可在docs/NonDockerInstallation.md中找到。

安装

推荐的本地开发环境获取方式是通过Docker。如果需要执行直接安装，请参阅非Docker安装文档。

注意： 流通管理器容器应可在amd64和arm64架构的机器上构建和运行。然而，由于当前依赖的ElasticSearch容器化版本存在差异，在arm64机器（包括使用Apple M1芯片系列的机器）上编排集群时，需使用不同的Docker Compose文件（docker-compose.arm64.yml）。如果使用以下make命令控制本地集群，则无需担心此差异，因为它会根据机器架构选择正确的compose文件。但如果在arm64机器上直接运行docker-compose命令，请确保通过docker-compose --file docker-compose.arm64.yml <COMMAND>使用正确的compose文件。

Docker

除安装Docker Desktop（上面链接）外，还需要https://hub.docker.com%E8%B4%A6%E5%8F%B7%E3%80%82Docker%E9%80%9A%E8%BF%87%E4%B8%8B%E8%BD%BD%E5%9F%BA%E7%A1%80%E6%9C%BA%E5%99%A8%E9%95%9C%E5%83%8F%E8%BF%9B%E8%A1%8C%E6%9E%84%E5%BB%BA%EF%BC%8C%E5%85%B6%E4%B8%AD%E5%A4%A7%E5%A4%9A%E6%95%B0%E5%8F%AF%E4%BB%8EDocker Hub获取。但Docker引擎只能代表已认证用户定位和拉取镜像。

创建账号（或使用现有账号）后，需通过Docker Desktop安装登录。可从Docker Desktop仪表板窗口的右上角进行登录。

Make

提供了Makefile以帮助管理流通管理器的本地容器。如果系统当前没有make，可从系统包管理器（apt、brew等）获取。如果无法安装或不愿安装make，也可手动运行Makefile中的命令，将命令复制粘贴到shell中执行。

克隆仓库并构建镜像

以下shell命令将克隆此仓库并为流通管理器Web应用和PostgreSQL数据库构建Docker镜像：

shell
git clone https://github.com/NYPL-Simplified/circulation.git
cd ./circulation
make build

为定时任务设置TZ

设置环境变量TZ为本地时区。默认时区为America/New_York。

操作

镜像成功构建后，可使用以下命令启动本地集群：

shell
make up

首次启动集群时，数据库容器将运行初始化脚本localdev_postgres_init.sh，该脚本创建开发和测试数据库，安装PostgreSQL扩展，并创建带凭证的用户。由于PostgreSQL数据目录持久化在Docker卷中，后续启动不会重新初始化数据库。Web应用容器将等待数据库可用并接受连接后才启动Web服务器。如果想观察初始化过程，可使用make up-watch代替make up，使终端保持连接以查看运行中容器的输出。

如果之前运行过容器化的流通管理器版本，可能会有残留的Docker卷用于持久化PostgreSQL数据目录。若该目录中的数据库配置不正确，make up-watch的输出可能如下：

Text
cm_local_db        | PostgreSQL Database directory appears to contain a database; Skipping initialization

[...]

cm_local_db        | 2021-11-19 22:20:06.563 UTC [74] FATAL:  password authentication failed for user "simplified"
cm_local_db        | 2021-11-19 22:20:06.563 UTC [74] DETAIL:  Role "simplified" does not exist.

[...]

cm_local_webapp    | --- Database unavailable, sleeping 5 seconds

此时，运行make clean删除现有卷，然后再次运行make up-watch，应能看到数据库初始化过程。

集群运行时（且Web服务器启动后），可通过http://localhost访问API端点，通过http://localhost/admin/访问管理Web应用。首次尝试登录管理应用时，将使用提供的凭证创建用户。

其他生命周期管理命令（完整列表可通过make help查看）：

• make stop / make start - 运行make up后，可暂停和恢复集群而不销毁容器
• make down - 停止集群并删除容器和虚拟网络
• make clean - 停止集群，删除容器、虚拟网络和数据库卷
• make full-clean - 与make clean相同，但还会删除集群的Docker镜像

访问容器

集群运行时，可使用以下命令访问容器：

• make db-session - 以超级用户身份在数据库容器上启动psql会话
• make webapp-shell - 在Web应用容器上打开bash shell
• make webapp-py-repl - 在Web应用容器上打开Python REPL会话（在项目虚拟环境中）
• make scripts-shell - 在脚本容器上打开bash shell
• make scripts-py-repl - 在脚本容器上打开Python REPL会话（在项目虚拟环境中）

测试

运行集群时，可使用以下命令启动测试套件：

shell
make test

这将通过pytest运行整个测试套件。如果希望使用pytest的-x选项在首次错误或失败时退出，可使用：

shell
make test-x

运行特定测试

可忽略Makefile，通过docker exec直接向Web应用容器发出pytest命令，如下所示：

shell
docker exec -it cm_local_webapp pipenv run pytest tests

这允许使用pytest的所有标准选项，例如：

shell
# 使用-x快速失败
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest -x tests

# 运行特定测试类
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest tests/test_controller.py::TestCirculationManager

# 运行特定测试方法
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest tests/test_controller.py::TestCirculationManager::test_exception_during_external_search_initialization_is_stored

# 关闭警告输出
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest --disable-warnings tests

pytest可执行文件的完整选项列表见[***]

代码变更

Web应用和脚本运行器的本地开发Docker容器（分别为cm_local_webapp和cm_local_scripts）的虚拟文件系统中没有代码库副本。相反，此仓库检出到的本地目录通过只读绑定挂载作为/home/simplified/circulation挂载到容器。该绑定挂载通过docker-compose设置，可在docker-compose.yml和docker-compose.arm64.yml的webapp和scripts部分查看。

由于这些主机挂载通过Docker Compose进行，如果直接通过docker run从构建的镜像创建容器，除非通过命令行选项指定绑定挂载，否则挂载不会存在，例如：

shell
docker run -d --rm --mount type=bind,source="$(pwd)",target=/home/simplified/circulation \
  --entrypoint tail circulation_webapp:latest -f /dev/null

通过绑定挂载本地目录，可在主机上进行更改，并在容器行为中看到反映。

在流通管理器管理界面添加馆藏

如果正在开发流通管理器管理界面，需要向本地应用添加图书馆藏进行测试，可遵循这些说明。

生成文档

使用Sphinx生成的代码文档可在本仓库的http://nypl-simplified.github.io/circulation/index.html%E4%B8%8A%E6%89%BE%E5%88%B0%E3%80%82%E7%9B%AE%E5%89%8D%E8%AE%B0%E5%BD%95%E4%BA%86%E6%9C%AC%E4%BB%93%E5%BA%93%E7%9A%84%60api%60%E7%9B%AE%E5%BD%95%E3%80%81%60scripts%60%E6%96%87%E4%BB%B6%E5%92%8C%60core%60%E5%AD%90%E6%A8%A1%E5%9D%97%E7%9B%AE%E5%BD%95%E3%80%82%E6%96%87%E6%A1%A3%E9%85%8D%E7%BD%AE%E4%BD%8D%E4%BA%8E%60/docs%60%E4%B8%AD%E3%80%82

Github Actions负责生成.rst源文件、生成HTML静态站点并将构建部署到gh-pages分支。

要_本地_查看文档，进入/docs目录并运行make html。这将生成.rst源文件并在/docs/build/html中构建静态站点。

使用Swagger(OpenAPI)的API文档可在/apidocs_admin和/apidocs_public端点找到。

持续集成

本项目通过Github Actions对新拉取请求和合并到默认develop分支时运行所有单元测试。相关文件位于.github/workflows/test.yml。贡献更新或修复时，要求所有python 3环境的测试Github Action通过。推送更改前本地运行tox命令，确保提交前发现所有失败测试。

如上所述，Github Actions还用于构建Sphinx文档并部署到Github Pages。相关文件位于.github/workflows/docks.yml。

使用NewRelic运行

此代码库包含使用NewRelic对API和后台脚本进行检测的配置，用于错误监控、指标等目的。默认情况下，本地开发禁用此功能，未进行特定配置部署时也不会运行。以下步骤假设已注册NewRelic账户并有权访问可用于检测应用的API密钥。

要在通过docker compose本地运行时进行检测，必须执行三个步骤：

1. 本地开发机器上必须运行NewRelic基础设施代理。macOS可通过brew安装，其他系统参见NewRelic文档
2. 根目录中必须提供.env文件，包含以下行：NEW_RELIC_LICENSE_KEY=[your_newrelic_key_here]
3. 当前使用的docker compose文件中必须将NEW_RELIC_MONITOR_MODE环境变量设置为'true'

要检测部署的流通管理器实例，必须向运行CM的docker容器提供以下环境变量作为运行时变量（具体方式取决于生产环境）：

• NEW_RELIC_APP_NAME：标识应用的字符串
• NEW_RELIC_MONITOR_MODE：字符串格式的布尔值
• NEW_RELIC_CONFIG_FILE：配置文件的绝对路径，未修改时应为/home/simplified/circulation/newrelic.ini
• NEW_RELIC_ENVIRONMENT：指定开发/测试/生产环境
• NEW_RELIC_LICENSE_KEY：NewRelic账户的API密钥

贡献

更多信息见此处。

许可

本项目是开源软件，采用Apache-2.0许可授权。

附录

查看https://github.com/NYPL-Simplified/Simplified/wiki%E8%8E%B7%E5%8F%96%E6%9C%89%E5%85%B3%E6%B5%81%E9%80%9A%E7%AE%A1%E7%90%86%E5%99%A8%E5%90%84%E7%A7%8D%E4%B8%BB%E9%A2%98%E7%9A%84%E6%9B%B4%E6%B7%B1%E5%85%A5%E4%BF%A1%E6%81%AF%E3%80%82