Cài đặt & chạy local

Thiết lập Data Explorer đúng với repo hiện tại: Prisma Migrate, backend NestJS, frontend Vite, và các biến môi trường cần thiết.

Dev setup khuyên dùng

Phù hợp nhất cho phát triển hằng ngày: chạy app metadata database, backend, và frontend riêng để debug nhanh hơn.

Docker là tùy chọn

Docker hữu ích khi bạn muốn có PostgreSQL local ổn định cho metadata app. Với repo hiện tại, manual setup vẫn là đường đơn giản nhất cho dev.

Local setup chuẩn

Clone repo và cài dependency cho root + từng workspace

Terminal

git clone https://github.com/KasierBach/Data-Explorer-Editor.git

cd Data-Explorer-Editor

npm install

npm install --prefix server

npm install --prefix client

Tạo file server/.env

Local run cần app metadata database, Redis, JWT secret đủ mạnh, encryption key đúng 32 ký tự, và `FRONTEND_URL`. OAuth và AI provider là tùy chọn.

server/.env

# Bắt buộc

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/data_explorer_dev?schema=public

JWT_SECRET=replace-with-a-strong-secret-at-least-32-chars

ENCRYPTION_KEY=replace-with-exactly-32-characters

FRONTEND_URL=http://localhost:5173

# Tùy chọn cho compatibility / local rules

LEGACY_ENCRYPTION_KEYS=

ALLOW_INTERNAL_IPS=false

ADMIN_EMAIL=admin@example.com

ADMIN_PASSWORD=your-secure-password

# Tùy chọn cho AI routing

GEMINI_API_KEY=...

AI_PROVIDER_TIMEOUT_MS=90000

AI_STREAM_IDLE_TIMEOUT_MS=90000

CEREBRAS_API_KEY=...

CEREBRAS_BASE_URL=https://api.cerebras.ai/v1

CEREBRAS_CHAT_MODEL=llama3.1-8b

OPENROUTER_API_KEY=...

OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

OPENROUTER_CHAT_MODEL=

GROQ_API_KEY=...

GROQ_BASE_URL=https://api.groq.com/openai/v1

GROQ_CHAT_MODEL=openai/gpt-oss-120b

BEEKNOEE_API_KEY=...

BEEKNOEE_BASE_URL=https://platform.beeknoee.com/api/v1

BEEKNOEE_CHAT_MODEL=glm-4.7-flash

Các biến AI trong `server/.env` cấu hình những lane dựng sẵn cho toàn hệ thống như Gemini, OpenRouter, Groq, Cerebras, và Beeknoee. Nếu bạn muốn thêm provider OpenAI-compatible riêng, hãy làm sau khi app chạy bằng `Hồ sơ > Cấu hình AI`; phần đó được lưu cục bộ trên máy người dùng chứ không nằm trong file env.

Đồng bộ schema app

Repo có migration PostgreSQL baseline đã commit. Dùng `migrate deploy` để áp dụng đúng lịch sử schema ở mọi môi trường.

Terminal

cd server

npx prisma migrate deploy

Chạy backend và frontend

Backend

cd server

npm run start:dev

Frontend

cd client

npm run dev

Tùy chọn: cấu hình AI trong UI

Sau khi đăng nhập, mở `Hồ sơ > Cấu hình AI` để chọn model riêng cho `AI Assistant`, `Explain`, `AI SQL`, `AI NoSQL`, và `Autocomplete`. Nếu bạn có provider OpenAI-compatible của riêng mình, nhập Base URL + API key rồi bấm `Tải model` để lấy danh sách model; nếu provider không trả catalog, bạn vẫn có thể nhập model thủ công.

Chạy từ root repo

Nếu muốn bật toàn bộ stack development bằng một lệnh, root repo đã có script `npm run dev`. Lưu ý: script này chỉ hoạt động khi `server/node_modules` và `client/node_modules` đã được cài trước.

Terminal

npm run dev

Docker notes

Docker phù hợp khi bạn muốn metadata database cục bộ ổn định hoặc không muốn cài PostgreSQL trực tiếp trên máy. Compose tự chạy `prisma migrate deploy`; dependency của `server` và `client` vẫn nên được cài riêng nếu bạn chạy dev ngoài container.

Docker

docker-compose up --build -d

Các địa chỉ local quan trọng

Frontend

http://localhost:5173

API

http://localhost:3001/api

Health

http://localhost:3001/api/health

Nếu backend không khởi động được sau khi sửa env, hãy kiểm tra `JWT_SECRET` và `ENCRYPTION_KEY` trước. Backend hiện fail-closed nếu secret yếu hoặc sai format. Nếu bạn đang dùng DB cloud, hãy nhớ local/network có thể chặn các cổng database như 5432, 3306, hoặc 27017.

Production build image một lần, chạy `npx prisma migrate deploy` trước khi start, và chỉ nhận traffic sau khi `/api/health/ready` xác nhận database cùng Redis đều sẵn sàng.

Lưu ý về timeout AI: code fallback và example file trong repo hiện đều dùng `90000ms`. Nếu local/dev của bạn cần fail nhanh hơn để debug, hãy chủ động hạ riêng giá trị này.

Trước đóHướng dẫn giao diện Tiếp theo Điều kiện tiên quyết

Sẵn sàng khám phá dữ liệu?

Tham gia cộng đồng trên GitHub để đóng góp cho IDE cơ sở dữ liệu địa phương thông minh nhất.

Mở Ứng dụng