apollo-config-client
一个轻量、同步、贴近 Apollo 官方 HTTP API 的 Python 配置中心客户端。
直接基于 Apollo 开放的 HTTP 接口实现,不依赖任何第三方 Apollo 专用客户端,版本兼容性最好,且对热更新逻辑完全可控。官方 Java / .NET 客户端底层使用的也是同一套接口,可稳定对接 Apollo 1.6 – 2.4.1。
特性
| 能力 | 说明 |
|---|---|
| 长轮询热更新 | 后台守护线程长轮询 notifications/v2,配置发布后秒级生效,并给出 key 级 diff |
| 本地容灾缓存 | 每次成功拉取都落盘;Apollo 全部不可用时,应用仍可用上一次的配置启动 |
| 访问密钥签名 | 兼容 Apollo 1.6+ 的 Access Key HMAC-SHA1 签名(匿名访问同样支持) |
| 类型化读取 | get_typed(namespace, Model) 用任意模型类(如 pydantic)解析配置 |
| 极简依赖 | 核心仅依赖 requests;pydantic 模型与 Oracle 助手都是可选 extra |
安装
pip install apollo-config-client # 核心(仅 requests)
pip install apollo-config-client[models] # + pydantic 领域模型 DatabaseConfig / LdapConfig
pip install apollo-config-client[oracle] # + init_oracle_thick_mode 助手
pip install apollo-config-client[all] # 以上全部
发布前请先在 https://pypi.org 确认包名
apollo-config-client可用;若被占用,备选apolloc/apollo-config。
快速开始
from apollo_config import create_config_manager_from_env
# 读环境变量 APOLLO_APP_ID / APOLLO_CONFIG_URL / APOLLO_NAMESPACES ...
cm = create_config_manager_from_env()
# 普通读取
cm.get_configs("application")
cm.get_value("feature_flag", "off")
# 订阅 namespace 变更,配置一发布即刻拿到 key 级 diff
@cm.on_namespace_change("database")
def _on_db_change(namespace, changes):
# 这里只做「置空 / 标记失效」等轻量操作,
# 真正的资源重建放到请求路径上惰性执行(避免回调里做重 IO)
rebuild_connection_pool_lazily()
显式参数创建(不走环境变量):
from apollo_config import create_config_manager
cm = create_config_manager(
app_id="my-app",
config_url="http://apollo-config-service:8080",
namespaces=["application", "database"],
access_key_secret="38fdae497a324263a5ad81aa387deee3", # 可选
)
用 pydantic 模型读取(可选 extra [models])
from apollo_config.contrib import DatabaseConfig
cfg = cm.get_typed("database", DatabaseConfig)
engine = create_engine(cfg.connection_url(), pool_size=cfg.pool_size)
设计要点
- 直接调用 Apollo 开放 HTTP API(官方客户端同款接口):
- 配置拉取:
GET {config_url}/configs/{appId}/{cluster}/{namespace} - 变更通知:
GET {config_url}/notifications/v2(HTTP 长轮询,秒级生效)
- 配置拉取:
- 热更新机制:后台守护线程长轮询
notifications/v2,一旦 Apollo 发布新配置, 客户端拉取最新值并计算 key 级 diff,触发业务注册的回调。 - 本地容灾缓存:每次成功拉取都会落盘到缓存目录;即使 Apollo 全部不可用, 应用也能用上一次的配置正常启动。
- 访问密钥签名:配置
access_key_secret后,对configs与notifications/v2两类请求统一做 HMAC-SHA1 加签;留空则走匿名访问,行为完全一致。
环境变量(用于 create_config_manager_from_env)
| 变量 | 说明 | 默认 |
|---|---|---|
APOLLO_APP_ID |
应用 AppId | apollo-app |
APOLLO_CONFIG_URL |
Config Service 地址(非 Portal 的 8070) | http://localhost:8080 |
APOLLO_CLUSTER |
集群 | default |
APOLLO_NAMESPACES |
逗号分隔的 namespace | application |
APOLLO_ENV |
环境名 | 空 |
APOLLO_ACCESS_KEY_SECRET |
访问密钥(可选) | 空 |
APOLLO_CACHE_DIR |
本地缓存目录 | .apollo_cache |
ORACLE_INSTANT_CLIENT |
Oracle Instant Client 路径(仅 11g 需要) | 空 |
示例应用
examples/ 下提供 Flask / FastAPI 两个完整示例(DB 连接池热重建):
cd examples
pip install -r requirements.txt # 会以 editable 方式安装本库
cp ../.env.example .env # 按需修改 Apollo 地址 / AppId
python flask_app.py # http://localhost:5000/config/database
# 或 python fastapi_app.py
与 flask_apollo_lab 的关系
本项目(库)原是从 flask_apollo_lab 中抽离出的通用部分(apollo/ + config/)。
flask_apollo_lab 作为消费方 / dogfooding 示例保留,可改为 pip install apollo-config-client
并 from apollo_config import ...,从而把"拷贝两个包"变成一行导入。
生产建议
- 脱敏:
password/bind_password等建议标记为 Apollo「私密配置」,对外接口务必脱敏(见public_dict())。 - 优雅关闭:进程退出前调用
config_manager.stop()停止长轮询线程(示例在settings.py用atexit注册)。 - 回调要快:变更回调里只做「置空 / 标记失效」这类轻量操作,真正的重建放到请求路径上惰性执行。
- 本地缓存目录
.apollo_cache/应加入.gitignore,不要提交到代码库。
Roadmap
- 多 Config Service 端点 / HA 故障转移(当前为单
config_url) - 可选的 async wrapper(基于
httpx或线程池),不进核心 - 配置变更事件的同步原语(如
watch()返回最新值的上下文管理器)
License
Metadata
Release files for apollo-config-client 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| apollo_config_client-0.1.0.tar.gz | 13.8 kB | With provenance | Details for apollo_config_client-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| apollo_config_client-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for apollo_config_client-0.1.0-py3-none-any.whl |
Total release size: 29.3 kB
Release files / apollo_config_client-0.1.0.tar.gz
| Download URL | apollo_config_client-0.1.0.tar.gz |
|---|---|
| Size | 13.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af824c680123dcdc3669042cc15e3abfa09a30f84c84e75528bc511856bc85fb
|
|
BLAKE2b-256 checksum How to use checksums |
97de309afa78c621ffcf4f14e83b4af1f8167b744bf1a585871f16495fa1efe8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 22, 2026.
Transparency logRelease files / apollo_config_client-0.1.0-py3-none-any.whl
| Download URL | apollo_config_client-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8e37808429e61497147d0cc9fb124083de0629ffc3e5c267d2466dfd809591a
|
|
BLAKE2b-256 checksum How to use checksums |
d05b13c75fda30f33f06d12ce3e424873374b25fa08a34f29b82fcd202d8492a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 22, 2026.
Transparency logSecurity for apollo-config-client 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for apollo_config_client-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.