安装部署指南

INSTALL FROM SOURCE CODE STEP BY STEP

Prerequisites

Architecture Overview

sysmex consists of two main components:

src/
├── api/          # Backend API service (Flask/Python)
└── cook-web/     # Script editor frontend (Next.js)

• api: Backend API service built with Flask
• cook-web: Script editor for creating and managing courses, built with Next.js

Required Tools and Services

• Python 3.11+ for backend API
• Node.js 22.16.0 for frontend applications
• MySQL 8.0+ for database storage
• Redis for caching and session management
• Docker & Docker Compose (recommended for easy deployment)

Required API Keys

At least one LLM provider must be configured:

• OpenAI API Key
• Baidu ERNIE API credentials
• ByteDance Volcengine Ark API Key
• SiliconFlow API Key
• Zhipu GLM API Key
• DeepSeek API Key
• Alibaba Qwen API Key

Optional Services

• Alibaba Cloud OSS for file storage
• Alibaba Cloud SMS for phone verification
• Langfuse for LLM tracking
• Email SMTP for email verification

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/lngyneric/ai-coach.git
cd ai-shifu

Step 2: Set Up Environment Variables

Copy the full environment template (already aligned with the Docker defaults):

cp docker/.env.example.full docker/.env

For Docker-based workflows the only mandatory edit is to add at least one LLM provider key (for example OPENAI_API_KEY, ERNIE_API_KEY, GLM_API_KEY, etc.). All other variables already have safe defaults that match the bundled MySQL/Redis services.

Step 3: Configure Environment Variables

Edit the .env file and configure the required settings.

Required Variables (MUST be configured)

These variables are essential for the application to run:

1. Database Connection

   • SQLALCHEMY_DATABASE_URI: MySQL connection string
   • Example: mysql://root:password@localhost:3306/ai-shifu?charset=utf8mb4

2. Security

   • SECRET_KEY: JWT signing key for authentication
   • Generate secure key: python -c "import secrets; print(secrets.token_urlsafe(32))"
   • Important: Use different keys for dev/test/prod environments

3. LLM Provider (at least one required)

   • Choose from: OpenAI, ERNIE, ARK, SiliconFlow, GLM, DeepSeek, Qwen
   • See .env.example.full for specific provider configurations

Configuration Reference

• docker/.env.example.full: canonical template that lists every environment variable with defaults, descriptions, and grouping (Database, Redis, Auth, LLM, etc.). Copy it to .env and edit in place.
• Docker reminder: the only required change for containerized installs is to set at least one LLM API key (e.g., OpenAI, ERNIE, GLM). Update database/Redis URLs only if you are not using the bundled services.

Important Notes

• All sensitive values (API keys, passwords) should be kept secure
• Never commit .env files to version control
• For production deployments, use environment-specific configurations
• Refer to the example files for detailed explanations of each variable

Step 4: Build Latest Docker Images & Start the Stack

1. Ensure docker/.env contains at least one LLM API key.
2. Build the backend and frontend images tagged as :latest from the repo root:

docker build -t aishifu/ai-shifu-api:latest -f src/api/Dockerfile .
docker build -t aishifu/ai-shifu-cook-web:latest -f src/cook-web/Dockerfile .

3. Start the containers with the compose bundle that tracks the :latest tags:

cd docker
docker compose -f docker-compose.latest.yml up -d

docker-compose.latest.yml always uses the most recent images (from Docker Hub or your own local builds). Use docker-compose.yml instead if you need pinned release tags for reproducible environments.

Step 5: Manual Installation (Development)

This section covers manual installation for development purposes or when you need more control over the setup.

Step 5.1: Set Up Database Services

Start MySQL and Redis services on your local machine or use Docker:

# Using Docker for databases only
docker run -d --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=ai-shifu -e MYSQL_DATABASE=ai-shifu mysql:latest
docker run -d --name redis -p 6379:6379 redis:latest

Step 5.2: Configure Environment for Local Development

Update your .env file for local development:

# Update database URLs for local services
SQLALCHEMY_DATABASE_URI="mysql://root:ai-shifu@localhost:3306/ai-shifu"
 
# Update API base URL
REACT_APP_BASEURL="http://localhost:5800"

Step 5.3: Start Backend API

cd src/api
# Copy the environment configuration from docker directory
cp ../../docker/.env .env
 
# Install Python dependencies
pip install -r requirements.txt
 
# Initialize database
flask db upgrade
 
# Start the API server
gunicorn -w 4 -b 0.0.0.0:5800 'app:app' --timeout 300 --log-level debug

Step 5.4: Start Cook Web Frontend & CMS

cd src/cook-web
# Copy the environment configuration from docker directory
cp ../../docker/.env .env
 
# Install Node.js dependencies
npm install  # or use pnpm install
 
# Start development server
npm run dev

Cook Web (which now serves both the learner experience and authoring console) will be available at http://localhost:3000.

Troubleshooting

Common Issues

1. Database Connection Failed

   • Ensure MySQL is running and accessible
   • Check database credentials in .env
   • Run flask db upgrade to initialize tables

2. Redis Connection Failed

   • Ensure Redis is running and accessible
   • Check Redis configuration in .env

3. LLM API Errors

   • Verify API keys are correct
   • Check API base URLs
   • Ensure the model name matches your provider

4. Frontend Build Failures

   • Ensure Node.js version is 22.16.0
   • Clear node_modules and reinstall: rm -rf node_modules && npm install
   • Check for environment variable issues

Log Files

• API logs: Check gunicorn output or /var/log/ai-shifu.log
• Frontend logs: Check browser console or terminal output

Access the Application

Manual Installation

• User Interface: http://localhost:3000 (or configured PORT)
• Script Editor: http://localhost:3001
• API: http://localhost:5800

Default Login

• Use any phone number for registration/login
• Default verification code: 1024