沐光 Paper 是面向数学建模竞赛写作流程的 SaaS 项目，覆盖题目与材料录入、AI 分模块生成、LaTeX 论文组装、在线编辑、自动编译修复和 PDF 下载。
本仓库是用于个人项目展示和技术交流的脱敏快照，代码基线来自原项目 2026 年 4 月 20 日提交 7c0e0727885aab65e7967241d4dd4c543b8c7611（“升级生成任务二十并发”）。为避免携带历史敏感数据，本仓库未复制原 Git 历史，也不包含生产配置、真实用户数据或可用凭据。
- 数学建模题面、分问代码、结果、参考资料及图片的统一录入
- 中文国赛和英文竞赛论文的分模块 AI 生成与顺序组装
- BullMQ 异步任务队列、用户级任务锁、模型链限流与并发控制
- LaTeX 在线编辑、图片管理、PDF 预览和版本文件管理
- 编译日志分析、结构检查和多轮 LaTeX 自动修复
- 用户、项目、订阅、支付、渠道、审计和运营后台基础能力
| 层级 | 技术 |
|---|---|
| Web | Next.js 14、React 18、Monaco Editor、PDF.js |
| API | NestJS、Fastify、Prisma、JWT、BullMQ |
| Worker | Node.js、TypeScript、BullMQ、Handlebars |
| 文档编译 | XeLaTeX、latexmk、TeX Live |
| 数据层 | PostgreSQL 15、Redis 7、本地对象存储适配器 |
| 网关与部署 | Docker Compose、Caddy |
flowchart LR
U[浏览器] --> W[Next.js Web]
U --> A[NestJS API]
W --> A
A --> DB[(PostgreSQL)]
A --> R[(Redis / BullMQ)]
A --> S[(项目文件存储)]
R --> Q[论文生成 Worker]
Q --> LLM[OpenAI 兼容模型接口]
Q --> T[提示词与论文模板]
Q --> L[XeLaTeX 编译服务]
Q --> S
L --> S
主要服务说明：
apps/web：用户端、管理端、论文生成表单和 LaTeX 编辑器。apps/api：鉴权、项目、文件、支付、建模会话、编译代理和后台接口。apps/worker：消费生成队列，调用模型，按模板装配论文并执行自动修复。apps/latex-compiler：隔离运行 XeLaTeX/latexmk，并提供健康检查与编译接口。compose：本地展示环境的 PostgreSQL、Redis、API、Worker、编译器、Web 和 Caddy 编排。proxy：本地反向代理示例。
更详细的数据流和模块边界见 架构说明。
- Linux、WSL2 或 macOS
- Docker 24+
- Docker Compose v2
- OpenSSL
- 建议至少 4 核 CPU、8 GB 内存和 15 GB 可用磁盘
git clone https://github.com/NewLifeLi/muguang_introduce.git
cd muguang_introduce./scripts/init-env.sh脚本会从 compose/env/.env.example 创建被 Git 忽略的 compose/env/.env.dev，并生成数据库密码、JWT Secret、内部回调密钥等本地随机值。
然后编辑 compose/env/.env.dev，至少填写：
LLM_CHAIN_KEYS=your_api_key默认模型接口采用 OpenAI 兼容协议。若使用其他供应商，同时调整：
LLM_CHAIN_BASES=https://your-provider.example/v1
LLM_CHAIN_MODELS=your-model-namemake config
make up
make migrate
make ps首次构建 LaTeX 镜像需要安装 TeX Live，耗时和磁盘占用会明显高于普通 Node.js 服务。
| 服务 | 地址 |
|---|---|
| Web | http://localhost:3000 |
| API 健康检查 | http://localhost:3001/health |
| LaTeX 健康检查 | http://localhost:3011/health |
| Caddy 统一入口 | http://localhost:8080 |
查看日志或停止服务：
make logs
make down各应用保留独立的 package-lock.json，可分别验证：
npm --prefix apps/api ci
npm --prefix apps/api run prisma:generate
npm --prefix apps/api run build
npm --prefix apps/worker ci
npm --prefix apps/worker run build
npm --prefix apps/latex-compiler ci
npm --prefix apps/latex-compiler run build
npm --prefix apps/web ci
npm --prefix apps/web run buildWeb 开发服务器：
npm --prefix apps/web run devAPI、Worker 和编译器依赖 PostgreSQL、Redis、共享存储及对应环境变量，开发时建议仍由 Docker Compose 提供基础服务。
| 变量 | 用途 | 是否必填 |
|---|---|---|
POSTGRES_PASSWORD |
本地 PostgreSQL 密码 | 是，由初始化脚本生成 |
JWT_SECRET |
Access/Refresh Token 签名 | 是，由初始化脚本生成 |
MODELING_INTERNAL_KEY |
API 与 Worker 内部建模接口鉴权 | 是，由初始化脚本生成 |
METRICS_CALLBACK_SECRET |
编译指标回调鉴权 | 是，由初始化脚本生成 |
LLM_CHAIN_BASES |
模型接口地址列表 | 生成论文时必填 |
LLM_CHAIN_KEYS |
模型 API Key 列表 | 生成论文时必填 |
LLM_CHAIN_MODELS |
每条链的候选模型 | 生成论文时必填 |
SMS_PROVIDER |
mock 或 aliyun |
本地默认 mock |
PAY_DEFAULT_CHANNEL |
sandbox、wechat 或 alipay |
本地默认 sandbox |
完整配置和说明位于 compose/env/.env.example。示例文件只包含空值或明确的本地非敏感配置。
本仓库的 Compose 文件用于本地演示，不应原样作为生产配置。生产环境至少需要：
- 使用云 Secret Manager、Docker Secrets 或受控环境变量注入凭据。
- 使用独立数据库账号、Redis 鉴权、TLS 和最小权限网络策略。
- 将对象存储、支付证书和短信凭据放在仓库之外。
- 关闭 Mock 短信和 Mock 支付入口。
- 对模型调用设置预算、速率限制、超时、重试和审计告警。
- 在反向代理层配置真实域名、HTTPS、安全响应头和上传限制。
- 本仓库不包含生产
.env、数据库转储、真实手机号、论文数据或支付数据。 - 原项目中的商业凭据已经从本公开快照中移除；提交前应继续运行密钥扫描。
- 原项目使用的商业系统字体未进入公开仓库，LaTeX 容器改用 Noto CJK 与 TeX Gyre 字体。
compose/env/.env.dev、secrets/、运行日志、生成论文和本地存储目录均被 Git 忽略。- 如果发现安全问题，请不要在公开 Issue 中提交密钥或用户数据，处理方式见 SECURITY.md。
该公开仓库展示的是一个经过脱敏的历史里程碑，并非线上商业环境的实时镜像。后续公开迭代会以安全、可复现的独立提交继续维护。
本仓库用于个人项目展示和技术评审，除仓库中另有说明的第三方组件外，项目自有代码保留全部权利。具体条款见 LICENSE。