admin/MuMuAINovel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update 2026-05-18 14:31:53

Browse Source
This commit is contained in:
yi
2026-05-18 14:31:54 +08:00
parent df33ce2f18
commit b77e2d8a7a
54 changed files with 1003 additions and 2699 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+216 -542
View File
@@ -1,643 +1,317 @@
# 墨木灵思 📚✨
<div align="center">
# 墨木灵思
![Version](https://img.shields.io/badge/version-1.4.8-blue.svg)
![Python](https://img.shields.io/badge/python-3.11-blue.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.109.0-green.svg)
![FastAPI](https://img.shields.io/badge/FastAPI-0.121.0-green.svg)
![React](https://img.shields.io/badge/react-18.3.1-blue.svg)
![License](https://img.shields.io/badge/license-GPL%20v3-blue.svg)
**基于 AI 的智能小说创作助手**
## 1. 项目简介
[特性](#-特性) • [快速开始](#-快速开始) • [配置说明](#%EF%B8%8F-配置说明) • [项目结构](#-项目结构)
### 项目概述
</div>
**墨木灵思**是一款基于大语言模型的智能小说创作平台，帮助作者从大纲、角色到章节一气呵成地完成创作，让 AI 成为可靠的写作搭档。
### 项目起源
长篇网文与原创小说创作往往面临设定繁杂、人物关系难梳理、章节衔接不连贯等问题。墨木灵思将 AI 能力融入创作全流程，把「灵感 → 大纲 → 角色 → 章节」串联为可管理的结构化工作流，降低创作门槛并提升产出效率。
### 项目定位
| 维度 | 说明 |
|------|------|
| **目标用户** | 网文作者、业余写作者、内容创作者、文学爱好者 |
| **适用场景** | 长篇连载、短篇创作、世界观搭建、同人续写、拆书仿写 |
| **部署形态** | 支持 Docker 一键部署，也可本地开发运行 |
### 核心价值
- 用 AI 辅助完成大纲、角色、世界观等前期设定，缩短冷启动时间
- 多模型灵活切换，适配不同文风与成本需求
- 角色关系、伏笔、职业体系等结构化管理能力，保持长篇一致性
- 多用户数据隔离，适合个人或小团队私有化部署
---
<div align="center">
## 2. 整体架构与技术栈
## 💬 加入交流群
### 系统架构
欢迎扫码加入 QQ 交流群，一起交流 AI 小说创作心得、反馈问题、获取最新动态！
采用**前后端分离**架构：React 单页应用负责交互，FastAPI 提供 REST API，PostgreSQL 持久化业务数据；生产环境通过 Docker Compose 编排应用与数据库，前端构建产物由后端静态托管，统一对外暴露 HTTP 服务。
<img src="frontend/public/qq.jpg" alt="QQ交流群二维码" width="300" />
```mermaid
flowchart LR
subgraph Client
UI[React SPA]
end
subgraph Server
API[FastAPI]
AI[AI 服务层]
DB[(PostgreSQL)]
Vec[ChromaDB / Embedding]
end
UI -->|HTTP / API| API
API --> AI
API --> DB
API --> Vec
AI -->|OpenAI 兼容 API| Ext[外部 LLM]
```
</div>
### 技术栈
| 分类 | 技术 | 版本 / 说明 |
|------|------|-------------|
| **后端** | Python | 3.11 |
| | FastAPI | 0.121.0 |
| | SQLAlchemy + Alembic | 2.0.25 / 1.14.0 |
| | Uvicorn | 0.38.0 |
| **前端** | React | 18.3.1 |
| | TypeScript + Vite | — |
| | Ant Design | 5.x |
| | Zustand | 5.x |
| **数据库** | PostgreSQL | 18（推荐） |
| | SQLite | 可选（开发 / 轻量场景） |
| **AI 与向量** | OpenAI / Anthropic SDK | 多模型接入 |
| | ChromaDB + Sentence Transformers | 长期记忆与语义检索 |
| **部署** | Docker + Docker Compose | 一键编排 |
| | GitHub Actions | 镜像构建与发布 |
### 技术选型说明
- **FastAPI**：异步性能好，自带 OpenAPI 文档，适合 AI 类长耗时接口。
- **PostgreSQL**：支持多用户、复杂关系与并发，满足生产级数据隔离。
- **React + Ant Design**：组件丰富，适合复杂表单与可视化（关系图、时间线等）。
- **Docker Compose**：降低部署成本，数据库与应用一键拉起。
---
<div align="center">
## 3. 项目目录概览
## 💖 支持项目
```
MuMuAINovel/
├── backend/ # 后端服务
│ ├── app/
│ │ ├── api/ # REST API 路由
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务逻辑（含 AI 调用）
│ │ ├── middleware/ # 中间件
│ │ ├── mcp/ # MCP 插件集成
│ │ └── main.py # 应用入口
│ ├── alembic/ # 数据库迁移
│ ├── scripts/ # 初始化与运维脚本
│ ├── static/ # 前端构建产物（生产）
│ └── requirements.txt
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── pages/ # 页面
│ │ ├── components/ # 通用组件
│ │ ├── services/ # API 封装
│ │ ├── store/ # 状态管理
│ │ └── theme/ # 主题配置
│ └── package.json
├── images/ # 文档与截图资源
├── storage/ # 用户生成资源（如封面）
├── logs/ # 运行日志
├── docker-compose.yml # 容器编排
├── Dockerfile # 镜像构建
└── README.md
```
如果这个项目对你有帮助，欢迎通过以下方式支持开发：
**[☕ 请我喝杯咖啡](https://mumuverse.space:1588/)**
**[🌐 MuMuのAPI站点](https://api.mumuverse.space/register?aff=4NN8)**
> 在 MuMu の API 站点充值满 50 元及以上，也可以获得下方赞助专属权益。
### 🎁 赞助专属权益
| 权益 | 说明 |
| 目录 | 作用 |
|------|------|
| 📋 **优先需求响应** | 您的功能需求和问题反馈将获得优先处理 |
| 🚀 **Windows一键启动** | 获取免安装 EXE 程序，双击即可使用 |
| 💬 **专属技术支持** | 加入赞助者内部群，获得远程协助和配置指导 |
### ☕ 赞助 / API 站点充值档位
| 金额 | 描述 |
|------|------|
| ¥5 | 🌶️ 一包辣条 |
| ¥10 | 🍱 一顿拼好饭 |
| ¥20 | 🧋 一杯咖啡 |
| ¥50 | 🍖 一次烧烤 |
| ¥99 | 🍲 一顿海底捞 |
您的支持是我持续开发的动力！🙏
</div>
| `backend/app/api/` | 项目、章节、角色、提示词等业务接口 |
| `backend/app/services/` | AI 生成、润色、向量记忆等核心逻辑 |
| `frontend/src/pages/` | 书架、项目详情、设置、提示词模板等页面 |
| `backend/alembic/` | PostgreSQL / SQLite schema 迁移 |
| `backend/scripts/` | 数据库初始化、入口脚本 |
---
## ✨ 特性
## 4. 核心业务功能
- 🤖 **多 AI 模型** - 支持 OpenAI、Gemini、Claude 等主流模型
- 📝 **智能向导** - AI 自动生成大纲、角色和世界观
- 👥 **角色管理** - 人物关系、组织架构可视化管理
- 📖 **章节编辑** - 支持创建、编辑、重新生成和润色
- 🌐 **世界观设定** - 构建完整的故事背景
- 🔐 **多种登录** - LinuxDO OAuth 或本地账户登录
- 💾 **PostgreSQL** - 生产级数据库，多用户数据隔离
- 🐳 **Docker 部署** - 一键启动，开箱即用
- **智能创作向导**：根据题材与设定，AI 自动生成大纲、角色档案与世界观框架。
- **多 AI 模型支持**：接入 OpenAI、Claude、Gemini 等，支持自定义 Base URL（兼容中转 API）。
- **项目管理与书架**：多项目并行，支持导入导出，便于备份与迁移。
- **角色与组织管理**：人物卡片、关系图谱、组织架构可视化编辑。
- **职业等级体系**：可自定义修仙境界、魔法等级等成长体系。
- **章节创作与润色**：章节生成、续写、重写、字数控制及 diff 对比。
- **世界观与大纲**：结构化维护故事背景与情节脉络。
- **伏笔管理**：追踪未回收伏笔，可视化时间线提醒。
- **灵感模式**：快速生成创作点子与情节灵感。
- **提示词工坊**：浏览、导入社区 Prompt 模板，可视化编辑自有模板。
- **拆书功能**：分析既有作品结构，辅助仿写与续写。
- **封面生成**：基于项目信息 AI 生成封面图。
- **长期记忆**：基于 Embedding 的语义记忆，保持跨章节一致性。
- **用户与认证**：本地账户、邮箱验证、LinuxDO OAuth；多用户数据隔离。
- **系统设置**：SMTP、AI 密钥、主题等可在线配置。
## 📸 项目预览
---
<details>
## 5. 实际应用场景示例
<summary>多图预警</summary>
### 适用行业与领域
<div align="center">
- 网络文学与自媒体连载
- 游戏、动漫、影视衍生文案
- 教育培训中的创意写作练习
- 个人 IP 与世界观孵化
### 登录界面
![登录界面](images/1.png)
### 典型场景
![登录界面](images/1-1.png)
**场景一：新人作者快速开书**
输入题材与基调后，由向导生成大纲与主要角色，再逐章扩写；适合从零起步、需要结构指引的作者。
### 主界面
![主界面](images/2.png)
**场景二：长篇连载一致性维护**
在数百章规模下，通过角色关系图、伏笔管理与向量记忆，减少人设崩坏与情节穿帮。
![主界面（暗色）](images/2-1.png)
**场景三：拆书仿写与风格学习**
导入参考作品或章节，分析结构后结合自身设定续写，用于练笔或同人向创作。
### 项目管理
![项目管理](images/3.png)
---
![项目管理](images/3-1.png)
## 6. 帮助解决的核心问题
### 赞助我 💖
![赞助我](images/4.png)
- **创作冷启动难**：自动生成大纲、角色与世界观，减少空白页焦虑。
- **设定易混乱**：关系图、职业体系、伏笔追踪让长篇设定可检索、可维护。
- **AI 调用分散**：统一配置多模型与 Prompt，降低切换成本。
- **协作与部署复杂**：Docker 私有化部署，数据留在自有环境。
- **章节质量不稳定**：润色、重写、分析建议一键应用，提升成稿效率。
- **提示词难以沉淀**：模板工坊与可视化编辑，复用优质 Prompt。
![赞助我](images/4-1.png)
---
</div>
## 7. 快速开始
</details>
### 环境要求
## 📋 TODO List
### ✅ 已完成功能
- [x] **灵感模式** - 创作灵感和点子生成
- [x] **自定义写作风格** - 支持自定义 AI 写作风格
- [x] **数据导入导出** - 项目数据的导入导出
- [x] **Prompt 调整界面** - 可视化编辑 Prompt 模板
- [x] **章节字数限制** - 用户可设置生成字数
- [x] **思维链与章节关系图谱** - 可视化章节逻辑关系
- [x] **根据分析一键重写** - 根据分析建议重新生成
- [x] **Linux DO 自动创建账号** - OAuth 登录自动生成账号
- [x] **职业等级体系** - 自定义职业和等级系统，支持修仙境界、魔法等级等多种体系
- [x] **角色/组织卡片导入导出** - 单独导出角色和组织卡片，支持跨项目数据共享
- [x] **伏笔管理** - 智能追踪剧情伏笔，提醒未回收线索，可视化伏笔时间线
- [x] **提示词工坊** - 社区驱动的 Prompt 模板分享平台，一键导入优质提示词
- [x] **拆书功能** - 目前呼声比较高的功能，一键拆书，给当年的ta一个圆满的结局
### 📝 规划中功能
......
> 💡 欢迎提交 Issue 或 Pull Request！
## 💻 硬件配置要求
### 最低配置（个人使用/开发环境）
| 组件 | 要求 |
| 方式 | 要求 |
|------|------|
| **CPU** | 2 核 |
| **内存** | 2 GB RAM |
| **存储** | 10 GB 可用空间 |
| **网络** | 稳定互联网连接（用于调用 AI API） |
| **Docker 部署（推荐）** | Docker 20.10+、Docker Compose 2.0+；至少一个 LLM API Key |
| **本地开发** | Python 3.11、Node.js 18+、PostgreSQL 18（或 SQLite）；稳定网络（调用外部 AI API） |
### 推荐配置（小型团队/生产环境）
**硬件建议（个人使用）**：2 核 CPU、2 GB 内存、10 GB 磁盘；生产或小团队建议 4 核 / 8 GB 内存。项目依赖外部 AI API，无需本地 GPU。
| 组件 | 要求 |
|------|------|
| **CPU** | 4 核 |
| **内存** | 8 GB RAM |
| **存储** | 20 GB SSD |
| **网络** | 稳定互联网连接 |
### 高并发配置（80-150 用户）
| 组件 | 要求 |
|------|------|
| **CPU** | 8 核 |
| **内存** | 16 GB RAM |
| **存储** | 50 GB+ SSD |
| **网络** | 高带宽连接 |
> **📌 说明**
> - **Embedding 模型**：约 400 MB 磁盘空间，运行时加载到内存
> - **PostgreSQL**：默认配置使用 256 MB shared_buffers，1 GB effective_cache_size
> - **Docker 部署**：建议预留额外 1-2 GB 内存给容器运行时
> - 本项目主要依赖外部 AI API（OpenAI/Claude/Gemini），不需要本地 GPU
## 🚀 快速开始
### 前置要求
- Docker 和 Docker Compose
- 至少一个 AI 服务的 API Key（OpenAI/Gemini/Claude）
### Docker Compose 部署（推荐）
### 安装步骤（Docker）
```bash
# 1. 克隆项目
git clone https://github.com/xiamuceer-j/墨木灵思.git
cd 墨木灵思
# 1. 获取项目代码
git clone <你的仓库地址>
cd MuMuAINovel
# 2. 配置环境变量（必需）
# 2. 配置环境变量
cp backend/.env.example .env
# 编辑 .env 文件，填入必要配置（API Key、数据库密码等）
# 编辑 .env：至少配置 AI API Key、数据库密码等
# 3. 确保文件准备完整
# ⚠️ 重要：确保以下文件存在
# - .env（配置文件，必需挂载到容器）
# - backend/scripts/init_postgres.sql（数据库初始化脚本）
# 4. 启动服务
docker-compose up -d
# 5. 访问应用
# 打开浏览器访问 http://localhost:8000
# 3. 确认必要文件存在
# - .env
# - backend/scripts/init_postgres.sql
```
> **📌 注意事项**
>
> 1. **`.env` 文件挂载**: `docker-compose.yml` 会自动将 `.env` 挂载到容器，确保文件存在
> 2. **数据库初始化**: `init_postgres.sql` 会在首次启动时自动执行，安装必要的PostgreSQL扩展
> 3. **自行构建**: 如需从源码构建，请先下载 embedding 模型文件（[加群获取](frontend/public/qq.jpg)）
### 使用 Docker Hub 镜像（推荐新手）
### 运行步骤
```bash
# 1. 拉取最新镜像（已包含模型文件）
docker pull mumujie/mumuainovel:latest
# 启动全部服务
docker compose up -d
# 2. 创建 docker-compose.yml（点击下方展开查看完整配置）
# 查看状态与日志
docker compose ps
docker compose logs -f
```
<details>
<summary>📄 点击展开 docker-compose.yml 完整配置</summary>
### 访问地址
```yaml
services:
postgres:
image: postgres:18-alpine
container_name: mumuainovel-postgres
environment:
POSTGRES_DB: ${POSTGRES_DB:-mumuai_novel}
POSTGRES_USER: ${POSTGRES_USER:-mumuai}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-123456}
POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
TZ: ${TZ:-Asia/Shanghai}
volumes:
- postgres_data:/var/lib/postgresql
- ./backend/scripts/init_postgres.sql:/docker-entrypoint-initdb.d/init.sql:ro
ports:
- "${POSTGRES_PORT:-5432}:5432"
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-mumuai} -d ${POSTGRES_DB:-mumuai_novel}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
networks:
- ai-story-network
command:
- postgres
- -c
- max_connections=${POSTGRES_MAX_CONNECTIONS:-200}
- -c
- shared_buffers=${POSTGRES_SHARED_BUFFERS:-256MB}
- -c
- effective_cache_size=${POSTGRES_EFFECTIVE_CACHE_SIZE:-1GB}
- -c
- maintenance_work_mem=${POSTGRES_MAINTENANCE_WORK_MEM:-64MB}
- -c
- checkpoint_completion_target=${POSTGRES_CHECKPOINT_COMPLETION_TARGET:-0.9}
- -c
- wal_buffers=${POSTGRES_WAL_BUFFERS:-16MB}
- -c
- default_statistics_target=${POSTGRES_DEFAULT_STATISTICS_TARGET:-100}
- -c
- random_page_cost=${POSTGRES_RANDOM_PAGE_COST:-1.1}
- -c
- effective_io_concurrency=${POSTGRES_EFFECTIVE_IO_CONCURRENCY:-200}
- -c
- work_mem=${POSTGRES_WORK_MEM:-4MB}
- -c
- min_wal_size=${POSTGRES_MIN_WAL_SIZE:-1GB}
- -c
- max_wal_size=${POSTGRES_MAX_WAL_SIZE:-4GB}
| 服务 | 默认地址 |
|------|----------|
| **Web 应用** | http://localhost:8000 |
| **API 文档（Swagger）** | http://localhost:8000/docs |
| **API 文档（ReDoc）** | http://localhost:8000/redoc |
| **PostgreSQL** | localhost:5432（容器内通过服务名 `postgres` 访问） |
mumuainovel:
image: mumujie/mumuainovel:latest
container_name: mumuainovel
depends_on:
postgres:
condition: service_healthy
ports:
- "${APP_PORT:-8000}:8000"
volumes:
- ./logs:/app/logs
- ./.env:/app/.env:ro
- ./storage/generated_covers:/app/backend/storage/generated_covers
environment:
# 应用配置
- APP_NAME=${APP_NAME:-墨木灵思}
- APP_VERSION=${APP_VERSION:-1.0.0}
- APP_HOST=${APP_HOST:-0.0.0.0}
- APP_PORT=8000
- DEBUG=${DEBUG:-false}
# 数据库配置
- DATABASE_URL=postgresql+asyncpg://${POSTGRES_USER:-mumuai}:${POSTGRES_PASSWORD:-123456}@postgres:5432/${POSTGRES_DB:-mumuai_novel}
- DB_HOST=postgres
- DB_PORT=5432
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-123456}
# PostgreSQL 连接池配置
- DATABASE_POOL_SIZE=${DATABASE_POOL_SIZE:-30}
- DATABASE_MAX_OVERFLOW=${DATABASE_MAX_OVERFLOW:-20}
- DATABASE_POOL_TIMEOUT=${DATABASE_POOL_TIMEOUT:-60}
- DATABASE_POOL_RECYCLE=${DATABASE_POOL_RECYCLE:-1800}
- DATABASE_POOL_PRE_PING=${DATABASE_POOL_PRE_PING:-True}
- DATABASE_POOL_USE_LIFO=${DATABASE_POOL_USE_LIFO:-True}
# 代理配置（可选）
- HTTP_PROXY=${HTTP_PROXY:-}
- HTTPS_PROXY=${HTTPS_PROXY:-}
- NO_PROXY=${NO_PROXY:-localhost,127.0.0.1}
# AI 服务配置
- OPENAI_API_KEY=${OPENAI_API_KEY:-}
- OPENAI_BASE_URL=${OPENAI_BASE_URL:-https://api.openai.com/v1}
- GEMINI_API_KEY=${GEMINI_API_KEY:-}
- GEMINI_BASE_URL=${GEMINI_BASE_URL:-}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
- ANTHROPIC_BASE_URL=${ANTHROPIC_BASE_URL:-}
- DEFAULT_AI_PROVIDER=${DEFAULT_AI_PROVIDER:-openai}
- DEFAULT_MODEL=${DEFAULT_MODEL:-gpt-4o-mini}
- DEFAULT_TEMPERATURE=${DEFAULT_TEMPERATURE:-0.7}
- DEFAULT_MAX_TOKENS=${DEFAULT_MAX_TOKENS:-32000}
# LinuxDO OAuth 配置
- LINUXDO_CLIENT_ID=${LINUXDO_CLIENT_ID:-11111}
- LINUXDO_CLIENT_SECRET=${LINUXDO_CLIENT_SECRET:-11111}
- LINUXDO_REDIRECT_URI=${LINUXDO_REDIRECT_URI:-http://localhost:8000/api/auth/linuxdo/callback}
- FRONTEND_URL=${FRONTEND_URL:-http://localhost:8000}
# 本地账户登录配置
- LOCAL_AUTH_ENABLED=${LOCAL_AUTH_ENABLED:-true}
- LOCAL_AUTH_USERNAME=${LOCAL_AUTH_USERNAME:-admin}
- LOCAL_AUTH_PASSWORD=${LOCAL_AUTH_PASSWORD:-admin123}
- LOCAL_AUTH_DISPLAY_NAME=${LOCAL_AUTH_DISPLAY_NAME:-本地管理员}
# 会话配置
- SESSION_EXPIRE_MINUTES=${SESSION_EXPIRE_MINUTES:-120}
- SESSION_REFRESH_THRESHOLD_MINUTES=${SESSION_REFRESH_THRESHOLD_MINUTES:-30}
- SESSION_COOKIE_SECURE=${SESSION_COOKIE_SECURE:-true}
restart: unless-stopped
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
networks:
- ai-story-network
> 若修改 `.env` 中 `APP_PORT`（例如 `10003`），访问地址为 `http://localhost:10003`。
volumes:
postgres_data:
driver: local
### 默认账号
networks:
ai-story-network:
driver: bridge
```
在 `.env` 中启用本地登录时，默认配置示例：
</details>
| 项 | 默认值 |
|----|--------|
| 用户名 | `admin` |
| 密码 | `admin123` |
```bash
# 3. 启动服务
docker-compose up -d
**请在生产环境中立即修改默认密码。**
# 4. 查看日志
docker-compose logs -f
### 本地开发（可选）
# 5. 更新到最新版本
docker-compose pull
docker-compose up -d
```
> **💡 提示**: Docker Hub 镜像已包含所有依赖和模型文件，无需额外下载
### 本地开发 / 从源码构建
#### 前置准备
```bash
# ⚠️ 重要：如果从源码构建，需要先下载 embedding 模型文件
# 模型文件较大（约 400MB），需放置到以下目录：
# backend/embedding/models--sentence-transformers--paraphrase-multilingual-MiniLM-L12-v2/
#
# 📥 获取方式：
# - 加入项目 QQ 群或 Linux DO 讨论区获取下载链接
# - 群号：见项目主页
# - Linux DO：https://linux.do/t/topic/1100112
```
#### 后端
**后端**
```bash
cd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
# 配置 .env 文件
cp .env.example .env
# 编辑 .env 填入必要配置
# 启动 PostgreSQL（可使用 Docker）
docker run -d --name postgres \
-e POSTGRES_PASSWORD=your_password \
-e POSTGRES_DB=mumuai_novel \
-p 5432:5432 \
postgres:18-alpine
# 启动后端
python -m uvicorn app.main:app --host localhost --port 8000 --reload
# 配置 DATABASE_URL 与 AI Key 后启动
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
#### 前端
**前端**
```bash
cd frontend
npm install
npm run dev # 开发模式
npm run build # 生产构建
npm run dev
```
## ⚙️ 配置说明
生产构建：`npm run build`，产物由后端 `backend/static` 托管。
### 必需配置
创建 `.env` 文件：
### 必需配置示例
```bash
# PostgreSQL 数据库（必需）
DATABASE_URL=postgresql+asyncpg://mumuai:your_password@postgres:5432/mumuai_novel
# 数据库（Docker 场景由 compose 注入，本地需自行填写）
POSTGRES_PASSWORD=your_secure_password
# AI 服务
OPENAI_API_KEY=your_openai_key
# AI 服务（至少配置一项）
OPENAI_API_KEY=your_key
OPENAI_BASE_URL=https://api.openai.com/v1
DEFAULT_AI_PROVIDER=openai
DEFAULT_MODEL=gpt-4o-mini
# 本地账户登录
# 本地登录
LOCAL_AUTH_ENABLED=true
LOCAL_AUTH_USERNAME=admin
LOCAL_AUTH_PASSWORD=your_password
```
### 可选配置
### 常见问题
```bash
# LinuxDO OAuth
LINUXDO_CLIENT_ID=your_client_id
LINUXDO_CLIENT_SECRET=your_client_secret
LINUXDO_REDIRECT_URI=http://localhost:8000/api/auth/callback
# PostgreSQL 连接池（高并发优化）
DATABASE_POOL_SIZE=30
DATABASE_MAX_OVERFLOW=20
# 会话 Cookie Secure 标记
# 默认 true，适合 HTTPS 部署；如果使用 HTTP 访问并且浏览器不保存登录 Cookie，可设为 false
SESSION_COOKIE_SECURE=true
```
> **🔐 Cookie Secure 说明**
>
> - HTTPS 部署：建议保持 `SESSION_COOKIE_SECURE=true`，浏览器只会通过 HTTPS 发送登录 Cookie。
> - HTTP 部署：如果登录后浏览器没有保存 Cookie，请在 `.env` 中设置 `SESSION_COOKIE_SECURE=false`，然后重启后端或 Docker 容器。
> - Docker Compose 示例默认使用 `SESSION_COOKIE_SECURE=${SESSION_COOKIE_SECURE:-true}`，如需关闭必须在 `.env` 中显式配置。
### 中转 API 配置
支持所有 OpenAI 兼容格式的中转服务：
```bash
# New API 示例
OPENAI_API_KEY=sk-xxxxxxxx
OPENAI_BASE_URL=https://api.new-api.com/v1
# 其他中转服务
OPENAI_BASE_URL=https://your-proxy-service.com/v1
```
## 🐳 Docker 部署详情
### 服务架构
- **postgres**: PostgreSQL 18 数据库
- 端口: 5432
- 数据持久化: `postgres_data` volume
- 初始化脚本: `backend/scripts/init_postgres.sql`（自动挂载）
- 优化配置: 支持 80-150 并发用户
- **mumuainovel**: 主应用服务
- 端口: 8000
- 日志目录: `./logs`
- 配置挂载: `.env` 文件
- 自动等待数据库就绪
- 健康检查: 每 30 秒检测一次
### 重要文件说明
| 文件 | 说明 | 是否必需 |
|------|------|---------|
| `.env` | 环境配置（API Key、数据库密码等） | ✅ 必需 |
| `docker-compose.yml` | 服务编排配置 | ✅ 必需 |
| `backend/scripts/init_postgres.sql` | PostgreSQL 扩展安装脚本 | ✅ 自动挂载 |
| `backend/embedding/models--*/` | Embedding 模型文件 | ⚠️ 自建需要 |
> **注意**: 使用 Docker Hub 镜像时，模型文件已包含在镜像中，无需额外下载
### 常用命令
```bash
# 启动服务
docker-compose up -d
# 查看状态
docker-compose ps
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
# 重启服务
docker-compose restart
# 查看资源使用
docker stats
```
### 数据持久化
- `./postgres_data` - PostgreSQL 数据库文件
- `./logs` - 应用日志文件
### 端口配置
修改 `docker-compose.yml` 中的端口映射：
```yaml
ports:
- "8800:8000" # 宿主机:容器
```
## 📁 项目结构
```
墨木灵思/
├── backend/ # 后端服务
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务逻辑
│ │ ├── middleware/ # 中间件
│ │ ├── database.py # 数据库连接
│ │ └── main.py # 应用入口
│ ├── scripts/ # 工具脚本
│ └── requirements.txt # Python 依赖
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── pages/ # 页面组件
│ │ ├── components/ # 通用组件
│ │ ├── services/ # API 服务
│ │ └── store/ # 状态管理
│ └── package.json
├── docker-compose.yml # Docker Compose 配置
├── Dockerfile # Docker 镜像构建
└── README.md
```
## 🛠️ 技术栈
**后端**: FastAPI • PostgreSQL • SQLAlchemy • OpenAI/Claude/Gemini SDK
**前端**: React 18 • TypeScript • Ant Design • Zustand • Vite
## 📖 使用指南
1. **登录系统** - 使用本地账户或 LinuxDO 账户
2. **创建项目** - 选择"使用向导创建"
3. **AI 生成** - 输入基本信息，AI 自动生成大纲和角色
4. **编辑完善** - 管理角色关系，生成和编辑章节
### API 文档
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request
### 贡献者
感谢所有为本项目做出贡献的开发者！
<a href="https://github.com/xiamuceer-j/墨木灵思/graphs/contributors">
<img src="https://contrib.rocks/image?repo=xiamuceer-j/墨木灵思" />
</a>
## 📝 许可证
本项目采用 [GNU General Public License v3.0](LICENSE)
**GPL v3 意味着：**
- ✅ 可自由使用、修改和分发
- ✅ 可用于商业目的
- 📝 必须开源修改版本
- 📝 必须保留原作者版权
- 📝 衍生作品必须使用 GPL v3 协议
## 🙏 致谢
- [FastAPI](https://fastapi.tiangolo.com/) - Python Web 框架
- [React](https://react.dev/) - 前端框架
- [Ant Design](https://ant.design/) - UI 组件库
- [PostgreSQL](https://www.postgresql.org/) - 数据库
## 📧 联系方式
- 提交 [Issue](https://github.com/xiamuceer-j/墨木灵思/issues)
- Linux DO [讨论](https://linux.do/t/topic/1106333)
- 加入QQ群 [QQ群](frontend/public/qq.jpg)
- 加入WX群 [WX群](frontend/public/WX.png)
| 问题 | 解决方案 |
|------|----------|
| 启动后无法访问 | 检查 `APP_PORT` 映射与防火墙；`docker compose ps` 确认容器健康 |
| 登录后 Cookie 未保存 | HTTP 部署时将 `SESSION_COOKIE_SECURE=false` 写入 `.env` 并重启 |
| AI 调用失败 | 核对 API Key、Base URL 及网络代理（`HTTP_PROXY` / `HTTPS_PROXY`） |
| 数据库连接失败 | 确认 PostgreSQL 容器已 healthy；检查 `DATABASE_URL` 用户名密码 |
| 自建镜像缺少 Embedding | 使用官方镜像或按文档将模型放入 `backend/embedding/` 目录 |
---
<div align="center">
## 8. 运行示例截图
**如果这个项目对你有帮助，请给个 ⭐️ Star！**
![image-20260518142402652](images/image-20260518142402652.png)
Made with ❤️
![image-20260518142411086](images/image-20260518142411086.png)
</div>
![image-20260518142620791](images/image-20260518142620791.png)
## Star History
![image-20260518142641345](images/image-20260518142641345.png)
<a href="https://www.star-history.com/#xiamuceer-j/墨木灵思&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=xiamuceer-j/墨木灵思&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=xiamuceer-j/墨木灵思&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=xiamuceer-j/墨木灵思&type=date&legend=top-left" />
</picture>
</a>
![image-20260518143108652](images/image-20260518143108652.png)
## History
![image-20260518143113951](images/image-20260518143113951.png)
![Alt](https://repobeats.axiom.co/api/embed/ee7141a5f269c64759302e067abe23b46796bafe.svg "Repobeats analytics image")
![image-20260518143117651](images/image-20260518143117651.png)
![image-20260518143121175](images/image-20260518143121175.png)
![image-20260518143125197](images/image-20260518143125197.png)
![image-20260518143134898](images/image-20260518143134898.png)