Arxi بوابة القرار أصل أساسي
Docs
أركسي دوكس

توثيق تسجيل الإثبات والأدلة المقاومة للتلاعب.

وثائق المنتجات الأخرى

أدوات تكوين وقت التشغيل الجانبية الكانونية التي تم إنشاؤها بواسطة arxi-contract.

تنزيل: config/sidecar.md (2.1 كيلوبايت) تنزيل: config/sidecar.schema.json (5.2 كيلوبايت) تنزيل: config/sidecar.compat.json (816 بايت) تنزيل: config/sidecar.example.toml (1.1 كيلوبايت)

إعدادات وقت تشغيل Arxi Sidecar

نظرة عامة

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

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

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

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

  • يتم رفض الحقول unknown على كل مستوى من مستويات التكوين.
  • 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 يجب ألا تمنح أذونات للمجموعة/الآخرين.
  • 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/arxi/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/arxi/arxi.sqlite3"

[transport]
mode = "tcp"

[transport.unix]
path = "/var/run/arxi/arxi.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/arxi/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
idempotency_ttl_seconds = 86400
idempotency_max_entries = 10000

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

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

sidecar.compat.json

{
  "api_major_version": 1,
  "baseline": {
    "hard_limits": {
      "max_header_bytes_hard_limit": 65536,
      "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"
      ],
      "transport_mode": [
        "unix",
        "tcp",
        "both"
      ]
    },
    "required_top_level_sections": [
      "config_version",
      "api",
      "recorder",
      "storage",
      "transport",
      "security",
      "limits",
      "signer",
      "logging"
    ]
  },
  "compatibility_policy": {
    "breaking_changes_require_major_bump": true,
    "deprecation_overlap_days_minimum": 180,
    "v1": "additive_only"
  },
  "config_version": 1
}

sidecar.schema.json

{
  "$id": "https://arxi.dev/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"
    },
    "limits": {
      "additionalProperties": false,
      "properties": {
        "idempotency_max_entries": {
          "minimum": 1,
          "type": "integer"
        },
        "idempotency_ttl_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "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",
        "idempotency_ttl_seconds",
        "idempotency_max_entries"
      ],
      "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"
        }
      },
      "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",
    "signer",
    "logging"
  ],
  "title": "Arxi Sidecar Runtime Config",
  "type": "object"
}