Ticketing الإعداد (متغيرات البيئة)
تأتي configuration من environment variables فقط. الأسماء case-insensitive والقيمة الفارغة unset، ولا يعني true إلا 1/true/yes/on. يوقف أي range/combination غير صالح startup. لا تستخدم scratch image قرصًا محليًا أو PV.
الإعدادات العامة وحدود الموارد
| Variable | Default | Allowed | Purpose |
|---|---|---|---|
SERVER_PORT | 5225 | valid u16 port | single client port; cluster advertises CLUSTER_SELF |
SOCKET_BIND | 0.0.0.0 | bindable address | client and Raft bind host |
DEBUG_MODE | build setting | flag | debug logging |
DOCKER_MODE | false | flag | official image binds internal 5225/6225 |
MAX_CONNECTIONS | 1024 | 1..8192 | concurrent client connections |
MAX_RAFT_CONNECTIONS | 64 | 1..256 | separate Raft/control reserve |
MAX_WAITERS | 2048 | 1..16384 | waiters per key; excess acquire gets B |
MAX_TOTAL_WAITERS | 16384 | MAX_WAITERS..65536 | total waiters; excess acquire gets B |
| Hard cap | Value | Saturation behavior |
|---|---|---|
| in-flight acquire per connection | 64 | B for that acquire |
| global in-flight acquire | 4096 | B for that acquire |
| global in-flight release | 512 separate lane | bounded wait until connection close |
| queued replies per connection | 256 | close slow client |
| coordinator channel | 4096 | backpressure |
| cluster active keys | 65536 | B for new-key acquire |
| Raft frame | 64MiB | reject RPC |
| encoded snapshot | 64MiB - 64KiB | reject build/install |
| concurrent Raft decode budget | 72MiB | bounded permit wait/timeout |
يستهدف default profile حد memory مقداره 512MiB. لا يمكن تجاوز hard ceilings ولا توجد قيمة unlimited.
مصادقة client وTLS
| Variable | Default | Purpose |
|---|---|---|
CLIENT_TOKENS | one empty token | comma-separated client credentials; production should use nonblank secrets |
TLS_CERT / TLS_KEY | unset | server certificate chain/private key; set together |
TLS_CA | system roots | CA for peer certificate verification |
TLS_SKIP_VERIFY | false | test only |
CLUSTER_ALLOW_PLAINTEXT_PRIVATE | false | explicit opt-out for isolated private networks |
يوصى بـTLS. يتطلب plaintext cluster opt-out صريحًا لشبكة خاصة ولا يوفر confidentiality أو certificate-based node identity.
هوية voter مستقرة
| Variable | Constraint | Purpose |
|---|---|---|
CLUSTER_ID | 1–128 ASCII alnum/./_/- | fencing domain |
CLUSTER_NODE_ID | u64 | Raft ID; never reuse after retirement |
CLUSTER_INCARNATION | non-zero u128 | freshly issued per process start |
CLUSTER_SELF | host:client-port | stable client slot and redirect address |
CLUSTER_RAFT_SELF | host:raft-port | unique Raft/control address for this process |
CLUSTER_PEERS | exactly 3 or 5 | NodeId@incarnation@client-address@raft-address entries |
كل cluster identity variables مطلوبة معًا؛ غيابها كلها يعني single mode. يحتاج كل process start إلى incarnation جديدة صادرة خارجيًا. لا يعاد استخدام retired NodeId؛ يدخل replacement كـlearner بـNodeId جديدة. Client/Raft ports صريحة ولا قاعدة +1000.
Startup admission هو fail-closed. لا يصبح initial cluster Open حتى يثبت كل peer حالة empty/unconsumed ويجتاز Prepared barrier. لا يفتح replacement إلا بعد one-shot Join. ترفض Pending/Prepared طلبات Vote وAppend وSnapshot وclient mutation. لا يُفترض peer غير متاح empty.
Raft وclock موثقة
| Variable | Default | Constraint |
|---|---|---|
CLUSTER_HEARTBEAT_MS | 500 | >=10 |
CLUSTER_ELECTION_TIMEOUT_MS | 2000 | >=600, >=4× heartbeat |
CLUSTER_SNAPSHOT_TIMEOUT_MS | 120000 | >=1000 |
RAFT_PROGRESS_TIMEOUT_MS | 10000 | >=1000 |
CLUSTER_CLOCK_AGENT_ENDPOINT | unset | required numeric IP:port in cluster |
CLUSTER_CLOCK_AGENT_SECRET | unset | required, at least 32 bytes, separate domain |
CLUSTER_CLOCK_PAIRWISE_DELTA_MS | 20 | 2..=60000, identical on all nodes |
CLUSTER_CLOCK_MAX_STALENESS_MS | 5000 | greater than sample interval + timeout |
CLUSTER_CLOCK_SAMPLE_INTERVAL_MS | 1000 | positive and below staleness |
CLUSTER_CLOCK_TIMEOUT_MS | 250 | positive and below staleness |
CLUSTER_CLOCK_MAX_RTT_MS | 50 | positive and at most timeout |
CLUSTER_CLOCK_MAX_UNCERTAINTY_MS | 2 | at most pairwise delta / 2 |
CLUSTER_CLOCK_MAX_SOURCE_AGE_MS | 2000 | positive |
يعيد clock endpoint authenticated reference time وuncertainty وsync state وsource age. فشل auth/freshness/RTT/pairwise delta/wall-step يوقف mutation وdrain clients ويغلق Raft.
مصادقة cluster وreplacement join
| Variable | Requirement |
|---|---|
CLUSTER_TOKENS | nonblank list required in cluster |
CLUSTER_CONTROL_TOKENS | nonblank list required in cluster |
CLUSTER_BOOTSTRAP_CREDENTIAL | initial cluster process only; recorded once in replicated state |
Replacement process values generated by prepare-replacement:
CLUSTER_JOIN_LEADERCLUSTER_JOIN_LEADER_NODE_IDCLUSTER_JOIN_LEADER_INCARNATIONCLUSTER_JOIN_CREDENTIALCLUSTER_JOIN_SEED_PEERS- fresh
CLUSTER_NODE_ID,CLUSTER_INCARNATION,CLUSTER_SELF,CLUSTER_RAFT_SELF,CLUSTER_PEERS
Credentials الخاصة بـcluster/control/clock/bootstrap/join domains منفصلة بلا reuse. Join values فقط من prepare-replacement؛ credential one-shot، default 60s والمسموح 5–300s. Peer wire يطابق CLUSTER_WIRE_VERSION=1 حرفيًا؛ لا تستخدم package version.