# circulation **Repository Path**: cinematique/circulation ## Basic Information - **Project Name**: circulation - **Description**: MOBEBR admin后端项目 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2023-06-27 - **Last Updated**: 2024-07-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Library Simplified Circulation Manager ![Build Status](https://github.com/nypl-simplified/circulation/actions/workflows/test.yml/badge.svg?branch=develop) ![GitHub Release](https://img.shields.io/github/release/nypl-simplified/circulation.svg?style=flat) ## 目录 * [概述](#概述) * [Git分支工作流程](#git分支工作流程) * [开发](#开发) * [安装](#安装) * [操作](#操作) * [测试](#测试) * [进行代码更改](#进行代码更改) * [将集合添加到流通管理器管理界面](#将集合添加到流通管理器管理界面) * [生成文档](#生成文档) * [持续集成](#持续集成) * [贡献](#贡献) * [许可证](#许可证) * [附录](#附录) ## 概述 这是[Library Simplified](https://www.librarysimplified.org/)的流通管理器。流通管理器是图书馆藏和Library Simplified的各种客户端应用（包括SimplyE）之间的主要连接。它处理用户认证，将有许可的作品与开放获取内容组合在一起，从分发商API和二级来源中提取更新的图书信息，并在适当组织的OPDS订阅中提供可用的图书。 ## Git分支工作流程 默认分支是`develop`，在进行错误修复或新功能的分支时应使用该工作分支。一旦将功能分支合并到`develop`，更改可以合并到`main`分支以创建发布版本。 其名称遵循`-deploy-`模式的分支是受保护的，并作为名为`organization`的组织的CI/CD流程的一部分使用。这些分支包括： * `nypl-deploy-qa` * `nypl-deploy-production` * `openebooks-deploy-qa` * `openebooks-deploy-production` * `bpl-deploy-qa` * `bpl-deploy-production` ## 开发 运行流通管理器实例的首选方法是使用Docker容器。如果由于某种原因无法运行容器化的流通管理器版本，则可以在[docs/NonDockerInstallation.md](./docs/NonDockerInstallation.md)中找到直接安装的初始说明。 ### 安装 获取本地开发环境的推荐方法是使用[Docker](https://www.docker.com/products/docker-desktop)。如果需要进行直接安装，请查看[Non-Docker Installation](./docs/NonDockerInstallation.md)文档。 _**注意：**流通管理器容器应在基于amd64和arm64的机器上构建和运行。然而，由于我们当前依赖的容器化版本的ElasticSearch存在差异，因此必须使用不同的Docker Compose文件（`docker-compose.arm64.yml`）来协调arm64机器上的群集，包括使用苹果的M1芯片系列的机器。如果您在本机上使用`make`命令来控制本地集群，这种差异并不重要，因为它会根据机器的体系结构选择正确的compose文件。然而，如果您在基于arm64的机器上直接运行`docker-compose`命令，请确保使用正确的compose文件，即`docker-compose --file docker-compose.arm64.yml `。_ #### Docker 除了安装Docker Desktop（上面的链接），还需要在[Docker Hub](https://hub.docker.com)上创建帐户。Docker工作原理是通过下载基础机器映像进行构建，并且其中大部分都可以从Docker Hub获得。然而，Docker Engine只能代表经过身份验证的用户定位并拉取图像。 一旦创建了帐户（或使用您已经拥有的帐户），您需要通过Docker Desktop安装来登录。您应该能够从Docker Desktop仪表板窗口的右上角执行此操作。 #### Make 为了简化流通管理器的本地容器管理，提供了一个[`Makefile`](./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 ``` ### 操作 成功构建镜像后，您可以使用以下命令启动本地集群： ```shell make up ``` 第一次启动集群时，数据库容器将运行初始化脚本 [`localdev_postgres_init.sh`](./docker/localdev_postgres_init.sh)，该脚本会创建开发和测试数据库、安装 PostgreSQL 扩展，并创建具有凭证的用户。由于 PostgreSQL 数据目录被持久化在 Docker 卷中，后续的启动将不会重新初始化数据库。Webapp 容器将等待数据库可用并接受连接后才启动其 Web 服务器。如果您想观察初始化过程，请使用 `make up-watch` 替代 `make up`，以保持终端连接到正在运行的容器的输出。 如果您之前曾运行过容器化的 Circulation Manager 版本，可能仍然存在一个 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` - 在 webapp 容器上打开一个 bash shell * `make webapp-py-repl` - 在 webapp 容器中的项目虚拟环境中打开一个 Python REPL 会话 * `make scripts-shell` - 在 scripts 容器上打开一个 bash shell * `make scripts-py-repl` - 在 scripts 容器中的项目虚拟环境中打开一个 Python REPL 会话 ### 测试 在运行集群的同时，您可以使用以下命令启动测试套件： ```shell make test ``` 这将通过 `pytest` 运行整个测试套件。如果您希望使用 `-x` 选项来使 `pytest` 在首次出现错误或失败时退出，可以使用以下命令： ```shell make test-x ``` #### 运行特定的测试 您可以忽略 `Makefile`，直接通过 `docker exec` 向 webapp 容器发出 `pytest` 命令，如下所示： ```shell docker exec -it cm_local_webapp pipenv run pytest tests ``` 这样可以让您访问所有标准的 `pytest` 选项，例如： ```shell # 使用 -x 快速失败 docker exec -it --env TESTING=1 cm_local_webapp pipenv run pytest -x tests # 运行特定的测试类 docker exec -it --env TESTING=1 cm_local_webapp pipenv \run pytest tests/test_decorators.py::TestDecorators # 运行特定的测试方法 docker exec -it --env TESTING=1 cm_local_webapp pipenv run pytest tests/test_decorators.py::TestDecorators::test_uses_location_from_ip # 关闭警告输出 docker exec -it --env TESTING=1 cm_local_webapp pipenv run pytest --disable-warnings tests ``` 完整的 `pytest` 可执行文件选项集可以在 [https://docs.pytest.org/en/6.2.x/usage.html](https://docs.pytest.org/en/6.2.x/usage.html) 上找到。 ### 代码更改 用于本地开发 web 应用程序和脚本运行程序的 Docker 容器（`cm_local_webapp` 和 `cm_local_scripts`）在其虚拟化文件系统中没有代码库的副本。相反，将此存储库检出的本地目录作为只读 [bind mount](https://docs.docker.com/storage/bind-mounts/) 提供给容器，路径为 `/home/simplified/circulation`。该 bind mount 的设置是通过 `docker-compose` 完成的，并且可以在 `docker-compose.yml` 和 `docker-compose.arm64.yml` 的 `webapp` 和 `scripts` 部分中找到。 由于这些主机挂载是通过 Docker Compose 实现的，如果您通过 `docker run` 直接从构建的镜像创建容器，除非您通过命令行选项指定 bind mount，否则它们将不会存在，例如： ```shell docker run -d --rm --mount type=bind,source="$(pwd)",target=/home/simplified/circulation \ --entrypoint tail circulation_webapp:latest -f /dev/null ``` 通过将本地目录作为 bind mount，您应该能够在主机 机器上进行更改，并且可以在容器的行为中看到这些更改的反映。 ### 向 Circulation Manager Admin 添加馆藏 如果您正在开发 Circulation Manager Admin，并且需要为测试目的向本地应用程序添加图书馆藏，您可以按照[这些说明](https://docs.google.com/document/d/1a0QNWTvt9NKChr8TcLJ3G1PfpBCKV6hC2JuB5Yk_CYY/edit?usp=sharing) 进行操作。 ## 生成文档 使用 Sphinx 生成的代码文档可以在本存储库的 [Github Pages](http://nypl-simplified.github.io/circulation/index.html) 上找到。目前，它包含了本存储库的 `api` 目录、`scripts` 文件以及 `core` 子模块目录的文档。文档的配置可以在 `/docs` 中找到。 Github Actions 用于生成 `.rst` 源文件、生成 HTML 静态网站，并将构建部署到 `gh-pages` 分支。 要在 _本地_ 查看文档，请进入 `/docs` 目录并运行 `make html`。这将生成 .rst 源文件，并在 `/docs/build/html` 中构建静态网站。 ## 持续集成 对于新的拉取请求和合并到默认的 `develop` 分支，此项目通过 Github Actions 运行所有单元测试。相关文件可以在 `.github/workflows/test.yml` 中找到。在提交更新或修复时，要求测试 Github Action 在所有 Python 3 环境中通过。在推送更改之前，请在本地运行 `tox` 命令以确保在提交之前找到任何失败的测试。 如上所述，Github Actions 还用于构建和部署 Sphinx 文档到 Github Pages。相关文件可以在 `.github/workflows/docks.yml` 中找到。 ## 贡献 有关更多信息，请参阅[此处](CONTRIBUTING.md)。 ## 许可证 本项目是根据 [Apache-2.0 许可证](LICENSE.md) 的开源软件。 ## 附录 查看 [NYPL Simplified Wiki](https://github.com/NYPL-Simplified/Simplified/wiki) 以获取有关与流通管理器相关的各种主题的更深入信息。