附录

本章汇总环境变量、Redis 键模式、API 端点与常用命令等速查表，便于入职与日常运维快速参考。

环境变量

变量	描述	默认值 / 示例
ALLOW_ORIGINS	CORS 允许的来源（逗号分隔）。	为空（禁用 CORS）。
ENABLE_TEST_ENDPOINTS	暴露 /__test__ 辅助端点。	false（docker-compose 中启用）。
MASTER_API_TOKEN	具备特权的 Bearer 令牌。	dev-master-token（docker-compose）。
SESSION_COOKIE_NAME	会话 Cookie 名称。	cirrus_session。
SESSION_TTL_SECONDS	会话有效期（秒）。	604800（7 天）。
COOKIE_SECURE	是否为 Cookie 设置 Secure。	false。
COOKIE_DOMAIN	Cookie 作用域域名。	为空（仅当前主机）。
COOKIE_SAMESITE	SameSite 策略（lax、none、strict）。	lax。
ENABLE_PASSWORD_AUTH	是否启用密码登录端点。	true。
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD	各组件共用的 Redis 参数。	redis / 6379 / 空。
ACMEDNS_BASE_URL	acme-dns 服务基础 URL。	http://acmedns。
ACME_DIRECTORY	ACME 目录地址（例如 Caddy 内部 CA）。	https://caddy:4431/acme/local/directory。
ACME_RENEW_CRON	续期扫描的 Cron 表达式。	0 * * * *。
ACME_RENEW_BEFORE_DAYS	距离到期多少天开始续期。	30。
ACME_RENEW_MAX_PER_SCAN	每次扫描排队的域名上限。	10。
ACME_LOCK_TTL	签发任务锁的 TTL。	900。
ACME_CERT_KEY_TYPE	Sewer 使用的密钥类型。	rsa2048。
ENFORCE_ACME_CNAME_CHECK	签发前是否要求 _acme-challenge CNAME 就绪。	true（非本地 CA）/ false。
WAIT_FOR_CNAME	签发前是否轮询 CNAME。	true。
CNAME_WAIT_SECS	等待 CNAME 的秒数。	10。
CNAME_BASE_DOMAIN	访问 FQDN 的根域。	cdn.local.test。
CNAME_REPLICAS_PER_SITE	每个域名分配的节点数。	2。
CNAME_DEFAULT_TTL	生成的 DNS 记录 TTL。	60。
DNS_MASTER_BIND_ADDR / DNS_MASTER_PORT	隐藏主监听地址/端口。	0.0.0.0 / 10053。
DNS_SOA_MNAME / DNS_SOA_RNAME / DNS_SOA_REFRESH / DNS_SOA_RETRY / DNS_SOA_EXPIRE / DNS_SOA_MINIMUM	SOA 参数。	依据基础域推导。
DNS_NS1_A / DNS_NS1_AAAA	权威 DNS glue 记录。	127.0.0.1 / 空。
CNAME_DNS_SLAVES	逗号分隔的从节点端点（host:port）。	172.28.0.12:10054。
NODE_HEALTH_PORT / NODE_HEALTH_INTERVAL_SECS / NODE_HEALTH_TIMEOUT_SECS / NODE_HEALTH_FAILS_TO_DOWN / NODE_HEALTH_SUCCS_TO_UP	健康检查配置。	9145 / 5 / 1 / 3 / 1。
CDN_PURGE_CHANNEL	清缓存消息的 Redis 通道。	cdn:purge。
FRONTEND_STATIC_DIR	前端静态资源目录。	/app/static。
INTERNAL_PURGE_BASE_URL	清缓存订阅器使用的基址。	http://127.0.0.1:8080。
NGX_METRICS_ALLOW（构建参数）	指标端点允许访问的 CIDR。	172.28.0.0/16（开发环境）。

Redis 键参考

键	类型	描述
cdn:domains	集合	所有管理的域名。
cdn:dom:{domain}	字符串（JSON）	域名配置（DomainConf）。
cdn:nodes	集合	已注册的节点 ID。
cdn:node:{id}	哈希	节点元数据（IP、active、健康计数）。
cdn:cert:{domain}	哈希	TLS 完整链、私钥、签发时间。
cdn:acme:{domain}	哈希	ACME 注册状态（用户名、密码、fulldomain、状态）。
cdn:acme:lock:{domain}	字符串	域名签发锁（值为任务令牌）。
cdn:acme:task:{domain}	字符串	当前排队/运行的任务 ID。
cdn:acmeacct:global	哈希	全局 ACME 账号密钥材料。
cdn:acmecertkey:{domain}	字符串	域名证书私钥 PEM。
cdn:acme:renew:scan_lock	字符串	续期扫描锁。
cdn:user:{username}	哈希	用户元数据（密码哈希、邮箱、状态、上次登录）。
cdn:users	集合	用户名集合。
cdn:tokens	集合	服务令牌 ID。
cdn:token:{id}	哈希	令牌元数据（标签、创建时间、哈希、后缀）。
cdn:token_hash:{hash}	字符串	基于哈希反查令牌 ID。
cdn:cname:dirty	发布/订阅通道	DNS 重建通知。
cdn:purge	发布/订阅通道	缓存清除通知。

核心 API 端点（摘要）

方法与路径	描述
POST /api/v1/auth/login	用户认证（密码）。
POST /api/v1/auth/logout	结束会话。
GET /api/v1/auth/me	查看当前用户上下文。
POST /api/v1/auth/change-password	修改自身密码。
GET /api/v1/domains	列出域名。
POST /api/v1/domains/{domain}	创建域名配置。
GET /api/v1/domains/{domain}	获取配置。
PUT /api/v1/domains/{domain}	更新配置。
DELETE /api/v1/domains/{domain}	删除域名。
GET /api/v1/domains/{domain}/cname	返回分配的边缘节点与 TTL。
PUT /api/v1/domains/{domain}/upstreams	更新源站列表。
PUT /api/v1/domains/{domain}/cache-rules	更新缓存设置。
PUT /api/v1/domains/{domain}/upstream-headers	更新转发头。
PUT /api/v1/domains/{domain}/cert	上传手动证书。
GET /api/v1/domains/{domain}/acme	查看 ACME 状态。
POST /api/v1/domains/{domain}/acme	入队 ACME 签发。
DELETE /api/v1/domains/{domain}/acme	清理 ACME 状态。
PUT /api/v1/nodes	更新节点清单。
POST /api/v1/purge	入队清缓存事件。
GET /api/v1/users	列出用户。
POST /api/v1/users	创建用户。
PUT /api/v1/users/{username}	更新用户。
DELETE /api/v1/users/{username}	删除用户。
GET /api/v1/auth/tokens	列出服务令牌（需 master 令牌）。
POST /api/v1/auth/tokens	创建服务令牌。
DELETE /api/v1/auth/tokens/{id}	删除服务令牌。

命令速查

命令	作用
just up	构建并启动完整栈（Docker compose）。
just down	停止栈并移除资源（含卷）。
just down-no-volumes	停止栈但保留卷。
just pytest	运行后端测试套件。
just quicktest	运行加速测试子集。
just fresh-test	重建容器并运行完整测试。
just fmt	自动格式化 Python 源码。
just deploy	执行 Ansible 部署（需设置 INVENTORY/PLAYBOOK）。

文档维护

保持本白皮书与代码库同步：

• 模块迁移或 API 变更时更新相应章节。
• 新增环境变量与 Redis 键要在此记录。
• 如发生重大架构变化（例如迁移至 Kubernetes），应新增小节或附录说明。

---

Cirrus CDN 以可扩展性与运维清晰度为核心设计。通过共享的架构、安全、自动化与运维认知，团队能在满足性能与合规目标的同时，自信地演进平台。