Khắc phục sự cố

Trang này cung cấp checklist và các bước chẩn đoán nhanh cho các lỗi thường gặp khi triển khai và vận hành HieraChain.

API không lên hoặc 404

• Kiểm tra tiến trình server:

  python -m hierachain.api.server
  

• Mặc định lắng nghe http://localhost:2661. Mở http://localhost:2661/docs để xác minh.

• Nếu cổng đổi khác: xem hierachain/config/settings.py (biến môi trường HRC_API_PORT).

401/403 khi gọi API

• Production có thể bật AUTH: settings.AUTH_ENABLED. Khi đó cần gửi API key:

  curl -H "X-API-Key: <your-key>" http://localhost:2661/api/v1/health
  

• Tên header tuỳ settings.API_KEY_NAME (mặc định X-API-Key).

Lỗi khi thêm sự kiện (schema mismatch)

• Đảm bảo payload có các trường bắt buộc:

  {
    "entity_id": "...",
    "event_type": "...",
    "details": {"k": "v"}
  }
  

• details là map. Giá trị không phải chuỗi sẽ bị chuyển sang chuỗi.

• Timestamp do server sinh; không cần gửi từ client.

Không tạo được Sub-Chain

• Endpoint tạo chuỗi:

  curl -X POST http://localhost:2661/api/v1/chains/supply_chain/create
  

• Tên chuỗi phải khớp regex [a-zA-Z0-9_\-]+ (xem kiểm tra trong api/v1/endpoints.py).

Sự kiện không xuất hiện trong block trả về

• Dùng API lấy block:

  curl "http://localhost:2661/api/v1/chains/supply_chain/blocks?limit=5&offset=0"
  

• Một số chuỗi cần gọi finalize/submit proof để thấy block mới. Thử submit proof:

  curl -X POST http://localhost:2661/api/v1/chains/supply_chain/submit-proof
  

Hiệu năng kém/503 Service Unavailable

• Nếu tích hợp ResourceGuardMiddleware, 503 có thể do CPU/RAM vượt ngưỡng.
• Kiểm tra cấu hình rate limit/HSTS/CORS trong settings.py.
• Giảm kích thước lô sự kiện, bật cache nâng cao nếu phù hợp (ADVANCED_CACHING_ENABLED).

Redis/SQLite không kết nối

• Kiểm tra biến môi trường:

• DATABASE_URL (SQLite/PostgreSQL)

• REDIS_HOST, REDIS_PORT, REDIS_DB

• Đổi DEFAULT_STORAGE_BACKEND về memory để cô lập sự cố lưu trữ.

V2 endpoints trả lỗi

• Xác minh API v2 đã được nạp (xem hierachain/api/server.py và hierachain/api/v2/endpoints.py).

• Thử health v2:

  curl -s http://localhost:2661/api/v2/health
  

Chữ ký/khóa

• Kiểm tra public key 64‑hex (Ed25519) khi đăng ký người dùng (security/identity.py).
• Dùng security/security_utils.py để sinh cặp khóa test.

Nhật ký và kiểm toán

• Bật mức log phù hợp, xem settings.LOG_LEVEL.
• Dùng risk_management/audit_logger.py cho vết kiểm toán.