تكوين وقت تشغيل Sidecar المسجل

نظرة عامة

يتم إنشاء هذا المستند من recorder-sidecar-config وهو المرجع القياسي لدلالات تكوين وقت تشغيل السايدكار.

أقسام المستوى الأعلى

config_version: يجب أن تكون 1.
api: تحتوي على major_version ويجب أن تكون 1.
recorder: هوية المسجل، محددات المخطط/الهاش، التحقق من بدء التشغيل، سياسة الإغلاق التلقائي.
storage: مسار ملف SQLite وضبط المتانة / نقطة التحقق.
transport: وضع النقل بالإضافة إلى إعدادات unix/tcp.
security: وضع المصادقة والتحكم في ملف الرمز.
probes (اختياري): سلوك الحضور/الجاهزية وسياسة الاعتماد.
enterprise (اختياري): سياسة تكامل المؤسسات وإعدادات التحكم في الطائرة.
limits: حدود الجسم/الرأس/التزامن/الوقت المستغرق.
ingest: التحكم في الطوابير، الدفعات الصغيرة، عدم التكرار، وضوابط تدفق البيانات.
signer: تمكين الموقّع ومسار مفتاح PKCS#8.
logging: مستوى السجل والتنسيق.

قواعد الفشل المغلق

يتم رفض الحقول unknown على كل مستوى من مستويات التكوين.
ملفات تكوين Sidecar محدودة إلى 1 ميجابايت.
hash_algorithm ثابت على sha256.
Non-loopback TCP requires security.mode = "token" and يتطلب TCP غير المتكرر security.mode = "token" و require_token_for_non_loopback = true.
Token files must be regular files, must not be symlinks, and on Unix must يجب أن تكون ملفات الرموز ملفات عادية، ويجب ألا تكون روابط رمزية، وعلى أنظمة Unix يجب ألا تمنح أذونات للمجموعة/الآخرين.
ملفات الرموز محدودة إلى 4096 بايت.
ملفات مفاتيح الموقّع مرتبطة بـ 65536 بايت.
max_header_bytes يجب ألا يتجاوز الحد الأقصى 65536.
وضع الإغلاق التلقائي يتطلب حقولًا محددة حسب الوضع (count, duration_seconds).
probes.enterprise_health_path must be an absolute path without control probes.enterprise_health_path يجب أن يكون مسارًا مطلقًا بدون أحرف تحكم.
probes.readiness_mode = "storage_and_enterprise" requires enterprise mode probes.readiness_mode = "storage_and_enterprise" يتطلب تفعيل وضع المؤسسة.

المثال القياسي

انظر Docs/generated/recorder/config/sidecar.example.toml.

الفنون القابلة للقراءة الآلية

sidecar.example.toml

config_version = 1

[api]
major_version = 1

[recorder]
recorder_id = "sidecar:production-01"
hash_algorithm = "sha256"
schema_version = 1
startup_verification_depth = 100

[recorder.auto_seal]
mode = "combined"
count = 1000
duration_seconds = 300

[storage]
path = "/var/lib/recorder/recorder.sqlite3"
sqlite_synchronous = "full"
sqlite_wal_autocheckpoint_pages = 1000
sqlite_busy_timeout_ms = 5000

[transport]
mode = "tcp"

[transport.unix]
path = "/var/run/recorder/recorder.sock"

[transport.tcp]
host = "127.0.0.1"
port = 9090
allow_non_loopback = false

[security]
mode = "token"
require_token_for_non_loopback = true
token_file = "/etc/recorder/token"

[probes]
readiness_mode = "storage_only"
enterprise_health_path = "/health"
ready_fail_on_admission_saturation = true

[enterprise]
mode = "disabled"
require_writer_lease_header = true

[limits]
max_request_body_bytes = 4194304
max_attachment_bytes = 1048576
max_concurrent_requests = 64
max_queued_requests = 128
request_timeout_seconds = 30
shutdown_drain_seconds = 10
max_header_bytes = 16384

[ingest]
queue_capacity = 8192
batch_max_commands = 256
batch_max_envelopes = 512
batch_max_bytes = 4194304
batch_max_wait_ms = 4
idempotency_ttl_seconds = 86400
idempotency_max_entries_per_stream = 10000
stream_roll_max_envelopes = 1000
stream_roll_max_duration_seconds = 300

[signer]
enabled = false
key_file = "/etc/recorder/signer.pem"

[logging]
level = "info"
format = "json"

sidecar.compat.json

{
  "api_major_version": 1,
  "baseline": {
    "hard_limits": {
      "config_file_max_bytes": 1048576,
      "max_header_bytes_hard_limit": 65536,
      "signer_key_file_max_bytes": 65536,
      "token_file_max_bytes": 4096,
      "token_min_length": 32
    },
    "optional_top_level_sections": [
      "enterprise",
      "probes"
    ],
    "required_enum_values": {
      "auto_seal_mode": [
        "none",
        "after_count",
        "after_duration",
        "combined"
      ],
      "enterprise_mode": [
        "disabled",
        "self_hosted_bootstrap",
        "managed_cloud"
      ],
      "log_format": [
        "json",
        "pretty"
      ],
      "log_level": [
        "error",
        "warn",
        "info",
        "debug",
        "trace"
      ],
      "readiness_mode": [
        "storage_only",
        "storage_and_enterprise"
      ],
      "security_mode": [
        "token",
        "open"
      ],
      "sqlite_synchronous": [
        "full",
        "normal",
        "extra"
      ],
      "transport_mode": [
        "unix",
        "tcp",
        "both"
      ]
    },
    "required_top_level_sections": [
      "config_version",
      "api",
      "recorder",
      "storage",
      "transport",
      "security",
      "limits",
      "ingest",
      "signer",
      "logging"
    ]
  },
  "compatibility_policy": {
    "breaking_changes_require_major_bump": true,
    "deprecation_overlap_days_minimum": 180,
    "v1": "pre_release_break"
  },
  "config_version": 1
}

sidecar.schema.json

{
  "$id": "https://arxiu.io/contracts/v1/config/sidecar.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Canonical sidecar runtime configuration schema.",
  "properties": {
    "api": {
      "additionalProperties": false,
      "properties": {
        "major_version": {
          "const": 1,
          "description": "Supported sidecar API major version.",
          "type": "integer"
        }
      },
      "required": [
        "major_version"
      ],
      "type": "object"
    },
    "config_version": {
      "const": 1,
      "description": "Config document version.",
      "type": "integer"
    },
    "enterprise": {
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "mode": {
                "enum": [
                  "self_hosted_bootstrap",
                  "managed_cloud"
                ]
              }
            }
          },
          "then": {
            "required": [
              "control_plane_base_url",
              "control_plane_token_file"
            ]
          }
        }
      ],
      "properties": {
        "control_plane_base_url": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "control_plane_token_file": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "default_namespace_id": {
          "minimum": 1,
          "type": [
            "integer",
            "null"
          ]
        },
        "mode": {
          "default": "disabled",
          "enum": [
            "disabled",
            "self_hosted_bootstrap",
            "managed_cloud"
          ],
          "type": "string"
        },
        "require_writer_lease_header": {
          "default": true,
          "type": "boolean"
        }
      },
      "required": [
        "mode",
        "require_writer_lease_header"
      ],
      "type": "object"
    },
    "ingest": {
      "additionalProperties": false,
      "properties": {
        "batch_max_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "batch_max_commands": {
          "minimum": 1,
          "type": "integer"
        },
        "batch_max_envelopes": {
          "minimum": 1,
          "type": "integer"
        },
        "batch_max_wait_ms": {
          "minimum": 1,
          "type": "integer"
        },
        "idempotency_max_entries_per_stream": {
          "minimum": 1,
          "type": "integer"
        },
        "idempotency_ttl_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "queue_capacity": {
          "minimum": 1,
          "type": "integer"
        },
        "stream_roll_max_duration_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "stream_roll_max_envelopes": {
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "queue_capacity",
        "batch_max_commands",
        "batch_max_envelopes",
        "batch_max_bytes",
        "batch_max_wait_ms",
        "idempotency_ttl_seconds",
        "idempotency_max_entries_per_stream",
        "stream_roll_max_envelopes",
        "stream_roll_max_duration_seconds"
      ],
      "type": "object"
    },
    "limits": {
      "additionalProperties": false,
      "properties": {
        "max_attachment_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "max_concurrent_requests": {
          "minimum": 1,
          "type": "integer"
        },
        "max_header_bytes": {
          "maximum": 65536,
          "minimum": 1,
          "type": "integer"
        },
        "max_queued_requests": {
          "minimum": 0,
          "type": "integer"
        },
        "max_request_body_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "request_timeout_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "shutdown_drain_seconds": {
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "max_request_body_bytes",
        "max_attachment_bytes",
        "max_concurrent_requests",
        "max_queued_requests",
        "request_timeout_seconds",
        "shutdown_drain_seconds",
        "max_header_bytes"
      ],
      "type": "object"
    },
    "logging": {
      "additionalProperties": false,
      "properties": {
        "format": {
          "enum": [
            "json",
            "pretty"
          ],
          "type": "string"
        },
        "level": {
          "enum": [
            "error",
            "warn",
            "info",
            "debug",
            "trace"
          ],
          "type": "string"
        }
      },
      "required": [
        "level",
        "format"
      ],
      "type": "object"
    },
    "probes": {
      "additionalProperties": false,
      "properties": {
        "enterprise_health_path": {
          "description": "Absolute path used for enterprise dependency readiness checks.",
          "minLength": 1,
          "pattern": "^/",
          "type": "string"
        },
        "readiness_mode": {
          "default": "storage_only",
          "enum": [
            "storage_only",
            "storage_and_enterprise"
          ],
          "type": "string"
        },
        "ready_fail_on_admission_saturation": {
          "default": true,
          "type": "boolean"
        }
      },
      "required": [
        "readiness_mode",
        "enterprise_health_path",
        "ready_fail_on_admission_saturation"
      ],
      "type": "object"
    },
    "recorder": {
      "additionalProperties": false,
      "properties": {
        "auto_seal": {
          "additionalProperties": false,
          "allOf": [
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "after_count"
                  }
                }
              },
              "then": {
                "required": [
                  "count"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "after_duration"
                  }
                }
              },
              "then": {
                "required": [
                  "duration_seconds"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "combined"
                  }
                }
              },
              "then": {
                "required": [
                  "count",
                  "duration_seconds"
                ]
              }
            }
          ],
          "properties": {
            "count": {
              "minimum": 1,
              "type": [
                "integer",
                "null"
              ]
            },
            "duration_seconds": {
              "minimum": 1,
              "type": [
                "integer",
                "null"
              ]
            },
            "mode": {
              "enum": [
                "none",
                "after_count",
                "after_duration",
                "combined"
              ],
              "type": "string"
            }
          },
          "required": [
            "mode"
          ],
          "type": "object"
        },
        "hash_algorithm": {
          "const": "sha256",
          "description": "Supported hash algorithm.",
          "type": "string"
        },
        "recorder_id": {
          "description": "Recorder identifier.",
          "maxLength": 256,
          "minLength": 1,
          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$",
          "type": "string"
        },
        "schema_version": {
          "description": "Envelope schema version.",
          "minimum": 1,
          "type": "integer"
        },
        "startup_verification_depth": {
          "description": "Read-back verification depth at startup.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "recorder_id",
        "hash_algorithm",
        "schema_version",
        "startup_verification_depth",
        "auto_seal"
      ],
      "type": "object"
    },
    "security": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "token",
            "open"
          ],
          "type": "string"
        },
        "require_token_for_non_loopback": {
          "type": "boolean"
        },
        "token_file": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "mode",
        "require_token_for_non_loopback",
        "token_file"
      ],
      "type": "object"
    },
    "signer": {
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "key_file": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "enabled",
        "key_file"
      ],
      "type": "object"
    },
    "storage": {
      "additionalProperties": false,
      "properties": {
        "path": {
          "description": "SQLite store path.",
          "minLength": 1,
          "type": "string"
        },
        "sqlite_busy_timeout_ms": {
          "description": "Optional SQLite busy-timeout in milliseconds.",
          "minimum": 1,
          "type": [
            "integer",
            "null"
          ]
        },
        "sqlite_synchronous": {
          "default": "full",
          "description": "SQLite synchronous durability mode.",
          "enum": [
            "full",
            "normal",
            "extra"
          ],
          "type": "string"
        },
        "sqlite_wal_autocheckpoint_pages": {
          "default": 1000,
          "description": "WAL autocheckpoint threshold in pages.",
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "transport": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "unix",
            "tcp",
            "both"
          ],
          "type": "string"
        },
        "tcp": {
          "additionalProperties": false,
          "properties": {
            "allow_non_loopback": {
              "type": "boolean"
            },
            "host": {
              "description": "IP literal host string.",
              "minLength": 1,
              "type": "string"
            },
            "port": {
              "maximum": 65535,
              "minimum": 1,
              "type": "integer"
            }
          },
          "required": [
            "host",
            "port",
            "allow_non_loopback"
          ],
          "type": "object"
        },
        "unix": {
          "additionalProperties": false,
          "properties": {
            "path": {
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "path"
          ],
          "type": "object"
        }
      },
      "required": [
        "mode",
        "unix",
        "tcp"
      ],
      "type": "object"
    }
  },
  "required": [
    "config_version",
    "api",
    "recorder",
    "storage",
    "transport",
    "security",
    "limits",
    "ingest",
    "signer",
    "logging"
  ],
  "title": "Recorder Sidecar Runtime Config",
  "type": "object"
}