Nautilus Trader Docker 服务与 PostgreSQL 测试环境搭建指南【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader本文基于仓库 .docker/README.md 编写完整介绍 Nautilus Trader 的 Docker 开发服务PostgreSQL、pgAdmin、Redis的启动、初始化与清理流程并深入解析其背后的docker-compose配置、Makefile 目标实现与 Rust 侧连接初始化源码。读者在阅读完本文后将能够独立完成本仓库 Postgres 集成测试环境的搭建与运行并理解测试环境与底层实现的对应关系。一、Docker 服务概览一次docker compose提供三套基础设施Nautilus Trader 的本地开发与集成测试依赖一组 Docker 服务全部定义在仓库的 .docker/docker-compose.yml 中。该 Compose 文件共声明了三个服务服务容器名镜像默认端口仅绑定 127.0.0.1postgresnautilus-databasepublic.ecr.aws/docker/library/postgres5432pgadminnautilus-pgadmindpage/pgadmin45051由PGADMIN_PORT控制redisnautilus-redispublic.ecr.aws/docker/library/redis6379值得注意的配置细节端口仅绑定回环地址三个服务的端口映射均为127.0.0.1:xxxx:xxxx服务不会被暴露到宿主机外部网络只允许本机访问这是本地测试场景下的安全默认值。凭据通过环境变量注入Postgres 的POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB均支持${VAR:-default}语法即未设置时使用默认值nautilus/pass/nautilus设置后则覆盖默认值。数据持久化Postgres 数据目录被设为容器内/data/postgresPGDATA并挂载到命名卷nautilus-databasepgAdmin 配置挂载到命名卷pgadmin。因此docker compose down停止不会丢失数据只有显式删除卷才会清空。安全加固三个服务都配置了security_opt: no-new-privileges:true禁止容器内进程提升权限pgAdmin 默认管理员邮箱为adminmail.com、密码为admin。网络与自愈三个服务共享nautilus-network网络均设置了restart: unless-stopped。各服务在项目中的用途PostgresNautilus Trader 的事件溯源与 Cache 数据库持久化后端承载nautilus-infrastructurecrate 的postgres特性基于 sqlx所依赖的数据库Redis用于 Redis 缓存的集成测试见 crates/infrastructure/tests/integration/test_cache_redis.rs对应redis特性pgAdminPostgres 的图形化管理界面方便在开发时直接查看表结构与数据。二、一键初始化make init-services做了什么根据 .docker/README.md从仓库根目录运行以下命令即可完成全部初始化make init-services该命令内部依次执行三个步骤对应 Makefile 中的init-services目标见 L1287-L1293启动容器调用make start-services等待就绪输出 Waiting for PostgreSQL to be ready... 并sleep 10给 Postgres 留出启动时间应用 Schema调用make init-db。start-services拉取镜像并启动全部服务start-services目标Makefile L1295-L1301的真实执行逻辑是bash scripts/ci/docker-pull-retry.sh public.ecr.aws/docker/library/postgres bash scripts/ci/docker-pull-retry.sh dpage/pgadmin4 bash scripts/ci/docker-pull-retry.sh public.ecr.aws/docker/library/redis docker compose -f .docker/docker-compose.yml up -d其中scripts/ci/docker-pull-retry.sh是仓库自带的镜像拉取重试脚本依次预拉取 postgres、pgadmin、redis 三个镜像带重试机制应对网络抖动随后以守护模式-d启动 Compose 中定义的全部服务。因此start-services实际会一次性启动 Postgres、pgAdmin 与 Redis 三个容器而不仅是 Postgres。init-db按序执行四个 SQL 文件init-db目标Makefile L1313-L1316将 schema 目录下四个 SQL 文件拼接后通过docker exec管道送入 Postgres 容器执行cat schema/sql/types.sql schema/sql/tables.sql schema/sql/functions.sql schema/sql/partitions.sql | docker exec -i nautilus-database psql -U nautilus -d nautilus这里通过容器名nautilus-database直接定位 Postgres 容器使用默认用户nautilus、默认数据库nautilus执行 SQL。四个文件的职责分别为schema/sql/types.sql创建 ENUM 与 DOMAIN 类型。例如ACCOUNT_TYPECASH/MARGIN/BETTING/WALLET、ORDER_STATUSINITIALIZED 到 VOIDED 的完整生命周期、BAR_AGGREGATIONTICK、VOLUME、MINUTE、RENKO 等等枚举以及I256、U256、U128、U160、I128等带范围约束 CHECK 的数值域类型用于承载 Nautilus 的高精度 128/256 位整数语义schema/sql/tables.sql创建各业务数据表schema/sql/functions.sql创建数据库函数schema/sql/partitions.sql创建分区表相关结构。默认连接参数速查参数默认值用户nautilus密码pass数据库nautilus端口5432三、运行 Postgres 集成测试Python 侧make test-postgresmake test-postgres该命令要求先执行过make init-services或至少make start-services后再make init-db即测试运行前必须存在已初始化 schema 的 Postgres 实例。Python 侧涉及 Postgres 的测试主要位于 python/tests/integration/test_live_node_cache.py该文件在无法连通 Redis / Postgres 服务时会以Redis and Postgres infrastructure services are not reachable为原因跳过测试见 L55 附近的reason并同时覆盖PostgresCacheConfig与RedisCacheConfig两种缓存后端L212 的pytest.param(PostgresCacheConfig, idpostgres)。Rust 侧直接使用cargo testPOSTGRES_HOSTlocalhost POSTGRES_PORT5432 POSTGRES_USERNAMEnautilus POSTGRES_PASSWORDpass POSTGRES_DATABASEnautilus \ cargo test -p nautilus-infrastructure --features postgres -- --test-threads1这条命令说明了几件关键事实测试包nautilus-infrastructurecrates/infrastructure其 Cargo.toml 中定义了postgres [dep:sqlx]特性必须显式启用postgres特性否则相关测试与代码不会被编译必须串行执行--test-threads1因为 Postgres 测试共享同一个数据库实例存在写冲突风险通过环境变量注入连接参数。四、环境变量如何驱动连接源码级解析上面的 Rust 测试命令注入的五个环境变量正是nautilus-infrastructure连接 Postgres 的标准入口。在 crates/infrastructure/src/sql/pg.rs 的get_postgres_connect_options函数L163-L191中连接参数的优先级为显式传入的参数 环境变量 默认值。具体对应关系如下环境变量含义解析失败行为POSTGRES_HOST主机地址回退到默认 hostPOSTGRES_PORT端口必须能被解析为u16否则 panicPOSTGRES_USERNAME用户名回退到默认用户名POSTGRES_PASSWORD密码回退到默认密码POSTGRES_DATABASE数据库名回退到默认数据库连接建立后connect_pg同文件 L198-L200通过PgPool::connect_with创建连接池而init_postgresL237 起则完成更完整的初始化创建publicschema、创建对应角色的LOGIN用户若已存在则跳过并记录日志、将 schema 所有权与数据库所有权移交给该角色最后执行 schema 目录下的 SQL 文件。从源码结构看这套初始化流程同时被 CLI 复用crates/cli/src/database/postgres.rs 的run_database_command在收到DatabaseCommand::Init时同样调用get_postgres_connect_options→connect_pg→init_postgres因此也可以使用 CLI 的database init命令完成相同工作参考 crates/cli/src/opt.rs 中的DatabaseOpt定义。五、Postgres 集成测试的验证依据仓库中实际的 Postgres 集成测试位于 crates/infrastructure/tests/integration/test_cache_database_postgres.rs。该测试文件在模块级声明了三个#[cfg]门控#[cfg(test)] #[cfg(feature postgres)] #[cfg(target_os linux)] // Databases only tested and supported on Linux即只有在启用postgres特性、且在 Linux 系统上运行时测试才会被编译执行——这解释了为什么 .docker/README.md 开头强调 Postgres integration tests run on Linux when a Postgres instance is available。测试内容覆盖CashAccount、各类 Instrument含audusd_sim、crypto_perpetual_ethusdt、futures_contract_es等测试桩、Order/Position、Signal、自定义数据等对象在PostgresCacheDatabase中的写入与查询并通过wait_until/wait_until_async等待异步就绪。另外仓库 CI 侧的引导脚本 scripts/ci/test-postgres-bootstrap.bash 展示了另一种更完整的验证路径动态启动一个一次性 Postgres 容器镜像固定为public.ecr.aws/docker/library/postgres:16.4-alpine等待pg_isready用管理员角色执行database init --schema $PWD/schema/sql初始化 schema 与角色再以nautilus用户运行测试最后还会校验角色创建结果。六、仅启动 Postgres 或清理环境只启动 Postgres不初始化 schema如果只想运行数据库容器、稍后再手动初始化可以使用docker compose -f .docker/docker-compose.yml up -d postgres然后从仓库根目录执行make init-db来应用 schema。停止与清理命令行为make stop-services停止全部容器docker compose down数据保留在命名卷中make purge-services停止并删除容器与卷docker compose down -v彻底清除数据两个目标分别对应 Makefile 中的stop-servicesL1303-L1306与purge-servicesL1308-L1311实现。若开发过程中需要彻底重置数据库状态应在stop-services之后使用purge-services删除命名卷再重新执行make init-services。七、其他 Docker 资源本仓库的 .docker 目录除docker-compose.yml与本文档外还包含多个可用于构建开发/发布镜像的 Dockerfile.docker/nautilus_trader.dockerfile主镜像多阶段构建基于rust:1.98.0-slim-bookworm与python:3.13-slim均按 digest 锁定版本以保障供应链安全安装 clang、capnproto 等构建依赖.docker/DockerfileUbuntuUbuntu 开发环境镜像配合 .docker/entrypoint.sh 使用entrypoint 会打印 Rust/UV 版本并设置PYO3_PYTHON环境变量支持交互式 shell 或直接执行传入命令.docker/jupyterlab.dockerfileJupyterLab 镜像Makefile 中通过make docker-build-jupyter构建.docker/preload-base-image.dockerfile基础镜像预热。这些文件与本文的测试服务编排共同构成了完整的本地开发与集成测试基础设施。八、常见问题与排查思路测试提示服务不可达确认容器已启动docker compose -f .docker/docker-compose.yml ps并确认端口映射正常注意端口只绑定127.0.0.1若在容器内或远程访问需要自行调整映射。schema 未初始化make init-db会静默拼接执行 SQL若报错请检查容器名是否为nautilus-database、用户/数据库是否为nautilus或直接改用make init-services全流程。Rust 测试未运行检查是否传入了--features postgres且当前系统是否为 Linux测试文件对target_os linux有硬性要求同时确认五个POSTGRES_*环境变量与 Compose 中的默认凭据一致。重复初始化init_postgres对已存在的角色、schema 会记录日志并跳过already exists 分支因此重复执行make init-db是安全的如需完全重置使用make purge-services删除卷后重新初始化。【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考