Ecbot Docs
Lập trình viên

Cấu hình

Mỗi ứng dụng Ecbot đọc cấu hình từ một tệp .env. Trang này liệt kê các tệp, những biến quan trọng và phần pnpm setup:local tự điền cho bạn.

Mỗi ứng dụng trong repo đọc cấu hình từ tệp .env riêng: apps/api/.env, apps/app/.env và apps/ai/.env. Mỗi tệp có một .env.example kèm chú thích bên cạnh. Chạy pnpm setup:local để tạo các tệp và điền mọi giá trị chỉ cần khớp giữa các ứng dụng; sau đó bạn thêm những khóa chỉ bạn mới lấy được.

pnpm setup:local

Tùy chọnTác dụng
(không có)Tạo các tệp .env còn thiếu, điền giá trị tự sinh và hỏi những khóa bạn phải cung cấp.
--yesDùng giá trị mặc định, không hỏi, và liệt kê các khóa bạn còn cần.
--checkBáo các giá trị còn thiếu hoặc không khớp, không thay đổi gì.
--origin <url>Thêm một origin khác mà API chấp nhận, ví dụ một frontend thứ hai. Dùng được nhiều lần.
--client-env <path>Ghi cặp khóa API mặc định vào tệp .env của một frontend khác.

Được điền sẵn: khóa ký JWT (ghi vào apps/api/keys) và mã khóa, các CORS origin, cặp khóa API dùng chung giữa API và ứng dụng web, cặp khóa giữa API và dịch vụ AI, cùng các bí mật nội bộ.

API (apps/api/.env)

NhómBiếnMục đích
Ứng dụngAPP_*, HOME_URL, HTTP_PORTTên, địa chỉ ứng dụng web dùng trong email và đường dẫn, cổng (8080).
Địa chỉ công khaiAPI_BACKEND_URLOrigin công khai của API, dùng cho webhook của kênh như Telegram.
CORSMIDDLEWARE_CORS_ORIGINCác origin của ứng dụng web được phép.
Cơ sở dữ liệuDATABASE_URLPostgres có tiện ích pgvector.
Xác thựcAUTH_JWT_*Địa chỉ JWKS, mã khóa và đường dẫn khóa.
RedisREDIS_*Bộ nhớ đệm và hàng đợi.
Lưu trữAWS_S3_PUBLIC_*, AWS_S3_PRIVATE_*Bucket cho tệp tải lên, tài liệu kiến thức và kỹ năng.
EmailRESEND_API_KEY, EMAIL_FROM, EMAIL_SUPPORTMã đăng ký, lời mời và cảnh báo. EMAIL_SUPPORT là địa chỉ hỗ trợ hiển thị trong email; để trống thì email không có dòng này.
KênhFACEBOOK_*, INSTAGRAM_*, ZALO_*, TELEGRAM_WEBHOOK_SECRET_TOKENỨng dụng của các kênh và xác minh webhook.
Dịch vụ AIAI_BACKEND_URL, AI_SERVICE_API_KEY, AI_SERVICE_API_SECRET, API_INTERNAL_TOKENGiao tiếp giữa API và dịch vụ AI.
Tác vụ nềnCLOUD_TASKS_*Dự án và hàng đợi Cloud Tasks, cùng CLOUD_TASKS_EMULATOR_HOST khi chạy trên máy.
Kho công cụCOMPOSIO_*Các công cụ trong kho công cụ.
Bảo mậtTURNSTILE_SECRET_KEY, OAUTH_TOKEN_ENCRYPT_KEYChống bot khi đăng ký và đăng nhập, mã hóa token kênh được lưu.

Ứng dụng web (apps/app/.env)

BiếnMục đích
VITE_API_URLOrigin của API, ví dụ http://localhost:8080.
VITE_API_KEY, VITE_API_KEY_SECRETCặp khóa API ứng dụng gửi kèm mọi yêu cầu.
VITE_TURNSTILE_SITE_KEYTiện ích chống bot.
VITE_FACEBOOK_*, VITE_INSTAGRAM_*, VITE_WHATSAPP_CONFIG_ID, VITE_ZALO_*Cửa sổ đăng nhập khi kết nối kênh. Instagram chỉ hiện khi đã đặt VITE_INSTAGRAM_APP_ID.

Dịch vụ AI (apps/ai/.env)

BiếnMục đích
OPENROUTER_API_KEY, OPENROUTER_BASE_URLCác mô hình ngôn ngữ. Bắt buộc.
POSTGRES_URL, RAG_POSTGRES_URLCơ sở dữ liệu và kho vector cho cơ sở kiến thức.
API_BASE_URL, AI_SERVICE_API_KEY, AI_SERVICE_API_SECRET, API_INTERNAL_TOKENGọi ngược về API. Phải khớp với giá trị bên API.
EMBEDDING_MODEL, EMBEDDING_DIMENSIONS, CHUNK_SIZE, CHUNK_OVERLAPCách chia nhỏ và nhúng tài liệu.
FIRECRAWL_API_KEYĐọc các trang web được thêm dạng URL.
ENV, LOG_LEVEL, LANGSMITH_*Môi trường, ghi log và theo dõi (tùy chọn).

Cổng

Dịch vụCổng
API8080
Ứng dụng web5173
Dịch vụ AI8000
Tài liệu5175
Postgres / Redis5432 / 6379
Trình giả lập Cloud Tasks8123
Máy chủ JWKS / Bull board3011 / 3010

Câu hỏi thường gặp

Máy chủ MCP Ecbot

Kết nối Claude Code, Codex hoặc Cursor với workspace bằng API key, để trợ lý AI quản lý agent, kiến thức, hội thoại và khách hàng giúp bạn.

Cấu trúc dự án

Ecbot là một monorepo pnpm và Turborepo gồm API NestJS, ứng dụng web React, dịch vụ AI Python và các package dùng chung. Đây là vị trí của từng phần.

Trong trang này

pnpm setup:localAPI (apps/api/.env)Ứng dụng web (apps/app/.env)Dịch vụ AI (apps/ai/.env)Cổng