FAQ khắc phục sự cố

Giải pháp cho các vấn đề Synapse phổ biến.

Tôi không thể đăng nhập

Triệu chứng

• POST /login trả về 401
• "Invalid email or password"

Giải pháp

1. Xác minh email chính xác — phân biệt chữ hoa chữ thường
2. Kiểm tra mật khẩu — tối thiểu 6 ký tự
3. Đăng ký trước nếu bạn không có tài khoản: POST /register
4. Đặt lại mật khẩu (nếu SMTP được cấu hình) qua giao diện web

Tôi mất Mind Key

Triệu chứng

• Không thể truy cập bộ nhớ
• Mind Key đã bị xóa/mất

Giải pháp

Mind Key không thể khôi phục. Bạn phải:

1. Đăng nhập để lấy JWT: POST /login
2. Liệt kê mind: GET /minds (với JWT)
3. Tạo mind mới: POST /minds
4. Lưu Mind Key mới
5. (Tùy chọn) Xóa mind cũ: DELETE /minds/:id

Dữ liệu trong mind cũ bị mất trừ khi bạn có thể tìm thấy Mind Key.

Lệnh gọi API trả về 401

Triệu chứng

• Tất cả lệnh gọi API trả về 401 Unauthorized
• "Mind Key fehlt oder ungültig"

Giải pháp

1. Xác minh định dạng header: Authorization: Bearer mk_...
2. Kiểm tra Mind Key bắt đầu bằng mk_ (không phải eyJ là JWT)
3. Kiểm tra trực tiếp:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

4. Mind Key có thể bị thu hồi — tạo mind mới

Xem Xác thực.

Lệnh gọi API trả về 404

Triệu chứng

• 404 Not Found
• "Route not found"

Giải pháp

1. Kiểm tra endpoint hợp lệ: curl https://synapse.schaefer.zone/endpoints
2. So sánh URL chính xác — phân biệt chữ hoa chữ thường, không có dấu gạch chéo cuối
3. Kiểm tra phương thức HTTP — GET /memory khác với POST /memory

Lệnh gọi API trả về 429

Triệu chứng

• 429 Too Many Requests
• "Rate limit exceeded"

Giải pháp

1. Chuyển sang xác thực header (không giới hạn tốc độ):

   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Đợi Retry-After giây nếu bạn phải dùng ?key=

Xem Giới hạn tốc độ.

Tìm kiếm bộ nhớ không trả về kết quả

Triệu chứng

• GET /memory/search?q=... trả về rỗng
• Biết bộ nhớ tồn tại

Giải pháp

1. Xác minh bộ nhớ tồn tại: GET /memory/recall
2. Kiểm tra cú pháp tìm kiếm — FTS5 có cú pháp cụ thể
3. Thử truy vấn đơn giản hơn — ?q=docker thay vì ?q=docker+swarm+deployment
4. Sử dụng tìm kiếm ngữ nghĩa cho truy vấn khái niệm: GET /memory/semantic-search?q=...

Xem Tìm kiếm FTS5.

Bộ nhớ không tồn tại

Triệu chứng

• POST /memory trả về thành công
• GET /memory/recall không hiển thị chúng

Giải pháp

1. Xác minh cùng Mind Key — key khác = mind khác
2. Kiểm tra phản hồi — POST trả về { "id": "mem_...", "status": "stored" }
3. Thử GET /memory (danh sách JSON) thay vì /memory/recall (văn bản)
4. Kiểm tra bộ lọc — ?category= hoặc ?tag= có thể ẩn chúng

Công cụ không xuất hiện trong Claude Desktop

Triệu chứng

• Claude Desktop hiển thị 0 công cụ
• Không có biểu tượng 🔌

Giải pháp

1. Khởi động lại Claude Desktop hoàn toàn (Cmd+Q)
2. Xác minh tệp cấu hình là JSON hợp lệ
3. Kiểm tra Node.js 18+ đã cài đặt
4. Chạy MCP thủ công: npx -y synapse-mcp-api@latest
5. Kiểm tra nhật ký: ~/Library/Logs/Claude/mcp.log

Xem Khắc phục sự cố MCP.

Synapse ngoại tuyến

Triệu chứng

• Không thể truy cập synapse.schaefer.zone
• curl hết thời gian chờ

Giải pháp

1. Kiểm tra internet của bạn — thử một trang khác
2. Kiểm tra sức khỏe Synapse: curl https://synapse.schaefer.zone/health
3. Đợi — có thể là sự cố tạm thời hoặc triển khai
4. Kiểm tra trang trạng thái (nếu có)

Cho tự lưu trữ: kiểm tra trạng thái Docker container, kết nối database.

Lỗi database

Triệu chứng

• 500 Internal Server Error
• "Database connection failed"

Giải pháp

Cho tự lưu trữ:

1. Kiểm tra PostgreSQL đang chạy: docker ps | grep postgres
2. Kiểm tra DATABASE_URL trong env
3. Kiểm tra migration: npm run migrate:check
4. Kiểm tra không gian đĩa: df -h

Cho phiên bản được lưu trữ: báo cáo cho hỗ trợ.

Webhook không kích hoạt

Triệu chứng

• Đã đăng ký webhook nhưng không nhận callback
• Không có POST đến URL của bạn

Giải pháp

1. Xác minh URL có thể truy cập: curl -X POST your-url -d '{}'
2. Kiểm tra bộ lọc sự kiện — memory.* khớp tất cả sự kiện memory
3. Kiểm tra webhook: POST /webhooks/:id/test
4. Kiểm tra webhook được bật: GET /webhooks/:id
5. Xác minh SSL — Synapse yêu cầu HTTPS hợp lệ cho URL webhook

Xem Webhooks API.

Cron job không chạy

Triệu chứng

• Đã tạo cron job nhưng không kích hoạt
• next_run không cập nhật

Giải pháp

1. Kiểm tra cú pháp lịch — phải là cron 5 trường HOẶC số nguyên giây hợp lệ
2. Xác minh endpoint được phép — phải là http(s), không IP riêng
3. Kiểm tra job được bật: GET /cron
4. Đợi thời gian lên lịch tiếp theo — cron không tức thời

Xem Cron & Scheduler.

Cần thêm trợ giúp?

1. Kiểm tra tài liệu hiện có: https://synapse.schaefer.zone/docs
2. Tìm kiếm tài liệu: GET /docs/search?q=your+question
3. Mở issue: https://gitlab.com/schaefer-services/synapse/-/issues
4. Liên hệ: xem trang /support

Bước tiếp theo

• Lỗi & Xử lý lỗi
• FAQ API
• Khắc phục sự cố MCP