diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 00000000..0b8232b1 --- /dev/null +++ b/dev/README.md @@ -0,0 +1,159 @@ +# MaxKB 开发环境 + +提供两种开发环境配置方案，根据需求选择使用。 + +## ⚠️ 重要说明 + +1. **首次启动较慢**：MaxKB 启动时需要初始化数据库、加载模型等，可能需要 3-5 分钟 +2. **镜像要求**：需要先构建本地镜像 `maxkb-local:latest` + ```bash + # 在项目根目录构建镜像 + docker build -f installer/Dockerfile -t maxkb-local:latest . + ``` + +## 方案一：最简单模式（推荐） + +使用官方镜像，通过挂载源码实现开发调试。 + +### 快速启动 + +```bash +cd dev + +# 方式一：使用启动脚本（推荐，会等待服务完全启动） +./start-dev.sh + +# 方式二：手动启动 +docker-compose -f docker-compose-simple.yml up -d +# 查看日志 +docker-compose -f docker-compose-simple.yml logs -f +``` + +访问： +- 应用地址：http://localhost:8081 +- 默认账号：admin / Admin@1234 + +### 特点 +- ✅ 一个容器包含所有服务（PostgreSQL、Redis、Django、Celery） +- ✅ Python代码修改自动重载 +- ✅ 最简单的配置 +- ❌ 前端需要手动构建才能看到效果 + +## 方案二：完整开发模式 + +分离前后端开发环境，支持前端热重载。 + +### 启动方式 + +```bash +cd dev + +# 启动所有服务 +docker-compose up -d + +# 仅启动后端 +docker-compose up -d maxkb-dev + +# 仅启动前端开发服务器 +docker-compose up -d frontend-dev +``` + +访问： +- Django后端：http://localhost:8080 +- 前端开发服务器（管理界面）：http://localhost:5173 +- 前端开发服务器（聊天界面）：http://localhost:5174 + +### 特点 +- ✅ 前后端都支持热重载 +- ✅ 前端使用Vite开发服务器，体验更好 +- ✅ 可以独立开发前端或后端 +- ❌ 配置相对复杂 + +## 开发流程 + +### 后端开发 + +1. 修改 `apps/` 目录下的Python代码 +2. Django开发服务器会自动检测变化并重载 +3. 查看容器日志观察变化： + ```bash + docker logs -f maxkb-dev + ``` + +### 前端开发 + +#### 方案一（简单模式） +1. 修改 `ui/` 目录下的代码 +2. 在容器内手动构建： + ```bash + docker exec -it maxkb-dev bash + cd /opt/maxkb-app + python main.py collect_static + ``` + +#### 方案二（完整模式） +1. 修改 `ui/` 目录下的代码 +2. Vite开发服务器自动热重载 +3. 访问 http://localhost:5173 查看效果 + +### 数据库操作 + +```bash +# 执行数据库迁移 +docker exec -it maxkb-dev python /opt/maxkb-app/main.py upgrade_db + +# 进入Django Shell +docker exec -it maxkb-dev python /opt/maxkb-app/apps/manage.py shell + +# 创建超级用户 +docker exec -it maxkb-dev python /opt/maxkb-app/apps/manage.py createsuperuser +``` + +## 常见问题 + +### 1. 端口冲突 +修改 docker-compose.yml 中的端口映射，例如： +```yaml +ports: + - "8081:8080" # 改为8081 +``` + +### 2. 权限问题 +如果遇到文件权限问题： +```bash +sudo chown -R $USER:$USER ../apps ../ui +``` + +### 3. 前端连接后端失败 +确保环境变量 `VITE_APP_BASE_URL` 设置正确： +```bash +VITE_APP_BASE_URL=http://localhost:8080 +``` + +### 4. 查看所有环境变量 +```bash +docker exec maxkb-dev env | grep MAXKB +``` + +## 生产镜像构建 + +如果需要构建自己的镜像： + +```bash +# 在项目根目录 +docker build -f installer/Dockerfile -t my-maxkb:dev . + +# 修改 docker-compose.yml 使用自定义镜像 +# image: my-maxkb:dev +``` + +## 清理环境 + +```bash +# 停止并删除容器 +docker-compose down + +# 清理所有数据（慎用） +docker-compose down -v +rm -rf ~/.maxkb-dev +``` \ No newline at end of file diff --git a/dev/dev.env b/dev/dev.env new file mode 100644 index 00000000..9ad2a644 --- /dev/null +++ b/dev/dev.env @@ -0,0 +1,30 @@ +# MaxKB Development Environment Configuration + +# Django Settings +DJANGO_DEBUG=True +DJANGO_SECRET_KEY=dev-secret-key-only-for-development +DJANGO_ALLOWED_HOSTS=* + +# Database (using internal PostgreSQL) +MAXKB_DB_HOST=127.0.0.1 +MAXKB_DB_PORT=5432 +MAXKB_DB_NAME=maxkb +MAXKB_DB_USER=root +MAXKB_DB_PASSWORD=Password123@postgres + +# Redis (using internal Redis) +MAXKB_REDIS_HOST=127.0.0.1 +MAXKB_REDIS_PORT=6379 +MAXKB_REDIS_PASSWORD=Password123@redis + +# Logging +MAXKB_LOG_LEVEL=DEBUG + +# API URLs +MAXKB_ADMIN_PATH=/admin +ADMIN_API_URL=/admin/api +CHAT_API_URL=/chat/api + +# Development specific +PYTHONUNBUFFERED=1 +WERKZEUG_DEBUG_PIN=off \ No newline at end of file diff --git a/dev/docker-compose-simple.yml b/dev/docker-compose-simple.yml new file mode 100644 index 00000000..effcde1c --- /dev/null +++ b/dev/docker-compose-simple.yml @@ -0,0 +1,27 @@ +# 最简化的开发环境配置 - 使用单容器模式 +version: '3.8' + +services: + maxkb: + # 使用官方镜像 + image: maxkb-local:latest + container_name: maxkb-dev + ports: + - "8081:8080" + volumes: + # 挂载Python源码 - 实现后端热重载 + - ../apps:/opt/maxkb-app/apps:rw + - ../main.py:/opt/maxkb-app/main.py:rw + + # 挂载前端源码 - 用于查看和调试 + - ../ui:/opt/maxkb-app/ui:rw + + # 数据持久化 + - ~/.maxkb-dev:/opt/maxkb + environment: + # 开启调试模式 + DJANGO_DEBUG: "True" + PYTHONUNBUFFERED: "1" + MAXKB_LOG_LEVEL: "DEBUG" + restart: unless-stopped + # 使用镜像默认的启动命令 \ No newline at end of file diff --git a/dev/docker-compose.yml b/dev/docker-compose.yml new file mode 100644 index 00000000..59064ed0 --- /dev/null +++ b/dev/docker-compose.yml @@ -0,0 +1,78 @@ +version: '3.8' + +services: + # maxkb-dev: + # # 使用生产镜像或本地构建的镜像 + # image: maxkb-local:latest + # # 如果需要本地构建，取消下面两行注释 + # # build: + # # context: ../ + # # dockerfile: installer/Dockerfile + # container_name: maxkb-dev + # ports: + # - "8080:8080" + # volumes: + # # 挂载Python源码实现热重载 + # - ../apps:/opt/maxkb-app/apps + # - ../main.py:/opt/maxkb-app/main.py + # - ../installer/maxkb.py:/opt/maxkb-app/maxkb.py + + # # 挂载UI源码（用于前端开发） + # - ../ui/src:/opt/maxkb-app/ui/src + # - ../ui/public:/opt/maxkb-app/ui/public + + # # 持久化数据 + # - maxkb_data:/opt/maxkb/data + + # # 开发配置 + # - ./dev.env:/opt/maxkb-app/.env + # environment: + # # 开发环境变量 + # DJANGO_DEBUG: "True" + # PYTHONUNBUFFERED: "1" + # MAXKB_LOG_LEVEL: "DEBUG" + + # # 数据库配置（使用内置的PostgreSQL） + # MAXKB_DB_HOST: "127.0.0.1" + # MAXKB_DB_PORT: "5432" + # MAXKB_DB_NAME: "maxkb" + # MAXKB_DB_USER: "root" + # MAXKB_DB_PASSWORD: "Password123@postgres" + + # # Redis配置（使用内置的Redis） + # MAXKB_REDIS_HOST: "127.0.0.1" + # MAXKB_REDIS_PORT: "6379" + # MAXKB_REDIS_PASSWORD: "Password123@redis" + # # 使用默认的启动命令，让容器内的所有服务正常启动 + # # command 留空使用镜像默认的 entrypoint + # networks: + # - maxkb-network + + # 独立的前端开发服务器（可选） + frontend-dev: + image: node:20-alpine + container_name: maxkb-frontend-dev + working_dir: /app + volumes: + - ../ui:/app + - /app/node_modules # 防止覆盖node_modules + ports: + - "5173:5173" # Vite开发服务器 + - "5174:5174" # Chat界面开发服务器 + environment: + - VITE_APP_BASE_URL=http://localhost:8080 + command: > + sh -c " + npm config set registry https://registry.npmmirror.com && + npm install && + npm run dev + " + networks: + - maxkb-network + +volumes: + maxkb_data: + +networks: + maxkb-network: + driver: bridge \ No newline at end of file diff --git a/dev/start-dev.sh b/dev/start-dev.sh new file mode 100755 index 00000000..ed24e327 --- /dev/null +++ b/dev/start-dev.sh @@ -0,0 +1,41 @@ +#!/bin/bash +# MaxKB 开发环境启动脚本 + +echo "启动 MaxKB 开发环境..." + +# 停止并删除旧容器 +docker-compose -f docker-compose-simple.yml down 2>/dev/null + +# 启动容器 +docker-compose -f docker-compose-simple.yml up -d + +echo "等待服务启动..." +echo "这可能需要几分钟时间，因为应用需要初始化..." + +# 等待服务启动 +max_attempts=60 +attempt=0 +while [ $attempt -lt $max_attempts ]; do + if docker exec maxkb-dev curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/admin/ | grep -q "200\|302"; then + echo "" + echo "✅ MaxKB 开发环境启动成功！" + echo "" + echo "访问地址：" + echo " - 应用地址: http://localhost:8081" + echo " - 默认账号: admin / Admin@1234" + echo "" + echo "查看日志：" + echo " docker logs -f maxkb-dev" + echo "" + exit 0 + fi + + printf "." + sleep 5 + attempt=$((attempt + 1)) +done + +echo "" +echo "❌ 服务启动超时，请检查日志：" +echo "docker logs maxkb-dev" +exit 1 \ No newline at end of file diff --git a/installer/Dockerfile b/installer/Dockerfile index bce62fa7..85338107 100644 --- a/installer/Dockerfile +++ b/installer/Dockerfile @@ -1,13 +1,26 @@ FROM node:24-alpine AS web-build + +# Configure npm to use npmmirror +RUN npm config set registry https://registry.npmmirror.com + COPY ui ui RUN cd ui && ls -la && if [ -d "dist" ]; then exit 0; fi && \ npm install --prefer-offline --no-audit && \ npm install -D concurrently && \ - NODE_OPTIONS="--max-old-space-size=4096" npx concurrently "npm run build" "npm run build-chat" && \ + NODE_OPTIONS="--max-old-space-size=8192" npx concurrently "npm run build" "npm run build-chat" && \ find . -maxdepth 1 ! -name '.' ! -name 'dist' ! -name 'public' -exec rm -rf {} + FROM ghcr.io/1panel-dev/maxkb-base:python3.11-pg17.6 AS stage-build +# Configure apt to use Aliyun mirror (for Debian 12 bookworm) +RUN if [ -f /etc/apt/sources.list.d/debian.sources ]; then \ + sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources && \ + sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources; \ + else \ + sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list && \ + sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list; \ + fi + ARG DEPENDENCIES=" \ python3-pip" @@ -19,15 +32,20 @@ RUN apt-get update && \ COPY --chmod=700 . /opt/maxkb-app WORKDIR /opt/maxkb-app + +# Configure pip to use Aliyun mirror +RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && \ + pip config set install.trusted-host mirrors.aliyun.com + RUN rm -rf /opt/maxkb-app/ui && \ python3 -m venv /opt/py3 && \ pip install uv --break-system-packages && \ . /opt/py3/bin/activate && \ - uv pip install -r pyproject.toml && \ + uv pip install -r pyproject.toml --index-url https://mirrors.aliyun.com/pypi/simple/ && \ find /opt/maxkb-app -depth \( -name ".git*" -o -name ".docker*" -o -name ".idea*" -o -name ".editorconfig*" -o -name ".prettierrc*" -o -name "README.md" -o -name "poetry.lock" -o -name "pyproject.toml" \) -exec rm -rf {} + && \ export MAXKB_CONFIG_TYPE=ENV && python3 /opt/maxkb-app/apps/manage.py compilemessages && \ export PIP_TARGET=/opt/maxkb-app/sandbox/python-packages && \ - uv pip install --target=$PIP_TARGET requests pymysql psycopg2-binary && \ + uv pip install --target=$PIP_TARGET --index-url https://mirrors.aliyun.com/pypi/simple/ requests pymysql psycopg2-binary && \ rm -rf /opt/maxkb-app/installer COPY --from=web-build --chmod=700 ui /opt/maxkb-app/ui diff --git a/installer/Dockerfile-base b/installer/Dockerfile-base index b39a7fa4..4070f812 100644 --- a/installer/Dockerfile-base +++ b/installer/Dockerfile-base @@ -19,7 +19,18 @@ ARG DEPENDENCIES=" \ RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \ echo "Asia/Shanghai" > /etc/timezone && \ + # Configure apt to use Aliyun mirror (for Debian 12 trixie) + if [ -f /etc/apt/sources.list.d/debian.sources ]; then \ + sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources && \ + sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources; \ + else \ + sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list && \ + sed -i 's/security.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list; \ + fi && \ apt-get update && apt-get install -y --no-install-recommends $DEPENDENCIES && \ + # Configure pip to use Aliyun mirror + pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && \ + pip config set install.trusted-host mirrors.aliyun.com && \ chmod 755 /usr/bin/start-*.sh && \ find /etc/ -type f ! -path '/etc/resolv.conf' ! -path '/etc/hosts' | xargs chmod g-rx && \ curl -L --connect-timeout 120 -m 1800 https://resource.fit2cloud.com/maxkb/ffmpeg/get-ffmpeg-linux | sh && \ diff --git a/ui/src/assets/logo/MaxKB-logo-currentColor.svg b/ui/src/assets/logo/MaxKB-logo-currentColor.svg index 94281645..ab59889a 100644 --- a/ui/src/assets/logo/MaxKB-logo-currentColor.svg +++ b/ui/src/assets/logo/MaxKB-logo-currentColor.svg @@ -1,20 +1,17 @@ - - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - + +Xbase + + \ No newline at end of file diff --git a/ui/src/assets/logo/MaxKB-logo.svg b/ui/src/assets/logo/MaxKB-logo.svg index beb86aa5..5e45acb9 100644 --- a/ui/src/assets/logo/MaxKB-logo.svg +++ b/ui/src/assets/logo/MaxKB-logo.svg @@ -1,64 +1,23 @@ - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + +Xbase + + \ No newline at end of file diff --git a/ui/src/assets/logo/logo-currentColor.svg b/ui/src/assets/logo/logo-currentColor.svg index 5f50e4cf..3a930567 100644 --- a/ui/src/assets/logo/logo-currentColor.svg +++ b/ui/src/assets/logo/logo-currentColor.svg @@ -1 +1,15 @@ -MaxKB \ No newline at end of file + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/ui/src/assets/logo/logo.svg b/ui/src/assets/logo/logo.svg index 2e601bb4..db4a218d 100644 --- a/ui/src/assets/logo/logo.svg +++ b/ui/src/assets/logo/logo.svg @@ -1 +1,21 @@ -MaxKB \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file