AI-CS/README.en.md

English | 中文

AI-CS — Intelligent Customer Service

Open-source AI customer service: AI + human agents, self-hostable, configurable, observable.
Ship a website chat widget and an agent dashboard together.

Table of Contents

• Preview
• Live Demo
• Features
• Project Structure
• Quick Start
• Configuration
• Knowledge Base (RAG)
• Multi-Instance WebSocket (Redis)
• Embed Widget (iframe)
• Documentation
• FAQ & Troubleshooting
• Star History
• Community
• Friendly Links
• Contributing
• License

Preview

Marketing homepage

Visitor chat widget

Human agent mode

AI mode

Live Demo

• Homepage: demo.cscorp.top
• Visitor chat: demo.cscorp.top/chat
• Agent login: demo.cscorp.top/agent/login

Features

• Visitor widget (embeddable)
  • Bottom-right chat window via iframe or widget.js
  • AI / human mode, sound notifications, file uploads
  • Optional per-turn web search (visibility configurable in admin)
• Agent dashboard
  • Conversation list, WebSocket messaging, unread badges
  • Visitor IP & approximate region (ip2region, offline)
  • Live typing draft sync between visitor and agent
  • Multi-model setup (text / image), prompts, knowledge base + RAG
  • Log center, analytics (widget opens, messages, AI success rate, etc.)
• Marketing site & SEO — metadata, OG, sitemap, robots.txt
• Optional web search — Serper (API or MCP) or provider-native search

Project Structure

AI-CS/
├── backend/                    # Go: API, WebSocket, AI, RAG
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── models/
│   ├── infra/                  # DB, Milvus, ip2region, storage
│   ├── websocket/
│   ├── router/
│   ├── data/                   # ip2region xdb (optional)
│   └── main.go
├── frontend/                   # Next.js: site, widget, agent UI
│   ├── app/
│   ├── components/
│   ├── features/
│   └── public/widget.js
├── doc/
├── scripts/
├── assets/readme/
├── docker-compose.yml
├── docker-compose.prod.yml
└── .env.example

Quick Start (root /.env only)

Copy .env.example to .env and set at least: MYSQL_ROOT_PASSWORD, DB_PASSWORD, ADMIN_PASSWORD, ENCRYPTION_KEY (64-char hex).

Option A — Pre-built images (recommended)

git clone https://github.com/2930134478/AI-CS.git
cd AI-CS
cp .env.example .env
# edit .env, then:
docker-compose -f docker-compose.prod.yml up -d

• Site: http://localhost:3000
• Chat: http://localhost:3000/chat
• Agent: http://localhost:3000/agent/login (admin / your ADMIN_PASSWORD)

Option B — Build with Docker Compose

docker-compose up -d --build

Option C — Local dev

• Go 1.24+, Node 20.9+, MySQL 8.0+
• go run main.go in backend/, npm run dev in frontend/

See the Chinese README for demo-site admin policies, port notes, and full deployment details.

Configuration (root /.env)

Full variable reference is in .env.example and the Chinese README configuration table.

Required for most deployments: database credentials, ADMIN_PASSWORD, ENCRYPTION_KEY, and (for production frontends) NEXT_PUBLIC_API_BASE_URL.

Knowledge Base (RAG)

• Disable Milvus: MILVUS_DISABLED=true — app still runs; RAG off
• Strict dependency: MILVUS_REQUIRED=true — exit if Milvus is unavailable

Multi-Instance WebSocket (Redis)

Configure REDIS_URL (or REDIS_ADDR + password) so WebSocket events sync across replicas. Single instance works without Redis.

Embed Widget (iframe)

Paste before </body>. Point iframe src to https://your-domain/chat. The page auto-detects iframe embed mode (no double floating button). See Chinese README for the full HTML snippet, or use frontend/public/widget.js.

Documentation

• None

FAQ & Troubleshooting

• No sound — browser needs a user gesture before audio
• Milvus startup failure — check MILVUS_REQUIRED; use MILVUS_DISABLED=true if you do not need RAG
• SEO / OG wrong — set NEXT_PUBLIC_SITE_URL
• “Init failed” / MySQL — curl :18080/health, docker logs ai-cs-backend; in Docker use DB_HOST=mysql

Star History

Community

• Bugs / feature requests：GitHub Issues (include deployment method and logs; never post API keys or DB passwords)
• QQ group：1106804464. It appears in the demo site footer under Contact.

Friendly Links

• Live demo
• ip2region — offline IP geolocation used by this project
• Suggest more links via Issues

Contributing

Issues and PRs welcome. For bugs, include deployment method, backend logs, and redacted .env keys.

License

MIT © 2025 2930134478