沐光 Paper

沐光 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]
    W --> A[NestJS API]
    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`	本地开发环境的服务编排和环境变量模板
`proxy`	Caddy 本地反向代理示例

更详细的数据流和信任边界见架构说明。

使用 Docker 的开发构建

这是本仓库推荐的本地验证方式。Compose 会构建 Web、API、Worker 和 LaTeX Compiler，并启动 PostgreSQL、Redis 和 Caddy。

1. 环境要求

Linux、WSL2 或 macOS
Docker 24 或更高版本
Docker Compose v2
Bash、OpenSSL 和 GNU Make
建议至少 4 核 CPU、8 GB 内存和 15 GB 可用磁盘

2. 克隆并初始化配置

git clone https://github.com/NewLifeLi/muguang_paper.git
cd muguang_paper
./scripts/init-env.sh

该脚本从 compose/env/.env.example 创建被 Git 忽略的 compose/env/.env.dev，并生成数据库密码、JWT Secret、内部回调密钥和本地沙箱口令。

编辑 compose/env/.env.dev，至少填写模型 API Key：

LLM_CHAIN_KEYS=your_api_key

默认使用 DashScope 的 OpenAI 兼容接口。使用其他供应商时同时修改：

LLM_PROVIDER=your-provider-name
LLM_CHAIN_BASES=https://your-provider.example/v1
LLM_CHAIN_MODELS=your-model-name

更新代码后，如果 .env.example 发生变化，可执行：

./scripts/init-env.sh --refresh

--refresh 会保留仍然有效的现有值，补入新变量，并移除已废弃变量，不会覆盖现有 API Key 或随机密钥。

3. 检查环境变量和 Compose

./scripts/check-env.sh compose/env/.env.dev
docker compose \
  --env-file compose/env/.env.dev \
  -f compose/docker-compose.yml \
  config --quiet

检查会拒绝空的必填项、废弃变量、没有源码消费者的变量、非法数值，以及当前短信或支付模式所缺少的条件配置。

对应的 Make 命令是：

make env-check
make config

4. 明确执行 Docker 开发构建

docker compose \
  --env-file compose/env/.env.dev \
  -f compose/docker-compose.yml \
  build --pull

等价的 Make 命令：

make build

首次构建 LaTeX 镜像需要安装 TeX Live，耗时和磁盘占用会明显高于普通 Node.js 服务。

5. 启动服务并部署数据库迁移

docker compose \
  --env-file compose/env/.env.dev \
  -f compose/docker-compose.yml \
  up -d

docker compose \
  --env-file compose/env/.env.dev \
  -f compose/docker-compose.yml \
  exec api npx prisma migrate deploy

docker compose \
  --env-file compose/env/.env.dev \
  -f compose/docker-compose.yml \
  ps

等价的 Make 命令：

make up
make migrate
make ps

修改代码后需要重建镜像时，可一次执行：

make dev

make dev 等价于 docker compose up -d --build。当前 Compose 是容器化本地开发构建，不包含源码目录热更新挂载；代码改动后需要重建对应镜像。

6. 访问与日志

服务	地址
Web	`http://localhost:3000`
API 健康检查	`http://localhost:3001/health`
LaTeX 健康检查	`http://localhost:3011/health`
Caddy 统一入口	`http://localhost:8080`

make logs
make down

make down 不会删除 PostgreSQL、Caddy 或共享文件卷。

环境变量生效边界

compose/env/.env.dev 同时作为 Compose 插值文件和应用容器的 env_file。已确认 .env.example 中的每个变量都有 Compose 或应用源码消费者。

配置组	实际生效位置
`POSTGRES_*`	Compose 的 PostgreSQL 服务和 API/Worker `DATABASE_URL`
`NEXT_PUBLIC_API`	Web 镜像构建参数，由 Next.js 在构建期内联
`API_PUBLIC_BASE`、`WEB_PUBLIC_ORIGIN`、`CORS_EXTRA_ORIGINS`	API 的回调地址、邀请链接和跨域策略
`JWT_*`、`SMS_CODE_SALT`	API 的令牌签名、有效期和验证码哈希
`MODELING_INTERNAL_KEY`、`METRICS_CALLBACK_SECRET`	API、Worker 和 LaTeX Compiler 的内部回调鉴权
`LLM_*`、`WORKER_CONCURRENCY`	Worker 的模型链、配额、超时和并发控制
`SMS_PROVIDER`、`ALIYUN_SMS_*`、`SMS_CALLBACK_TOKEN`	API 的 Mock/阿里云短信适配器与回调鉴权
`PAY_`、`WECHAT_`	API 的本地沙箱或微信支付 V3 适配器
`LATEX_*`	Worker 自修复流程和 API/编译器超时
`USER_IMG_QUOTA_BYTES`、`INPUT_IMG_MAX_PER_QUESTION`	API 上传限制，并在 Web 镜像构建时同步给前端

下列旧变量已从开发模板移除：

WECHAT_APP_SECRET：当前微信支付 V3 Native 适配器不读取该值。
REDIS_URL、STORAGE_LOCAL_ROOT、API_INTERNAL_BASE、LATEX_ENDPOINT：Docker 内部地址由 Compose 按服务名固定注入，不再伪装成可由 .env.dev 覆盖的用户配置。
METRICS_COMPILE_CALLBACK_KEY、METRICS_INTERNAL_KEY：历史别名已移除，统一使用 METRICS_CALLBACK_SECRET。

JWT_ACCESS_EXPIRES 和 JWT_REFRESH_EXPIRES 必须填写整数秒，不能填写 15m 或 30d。

不使用 Docker 的构建验证

需要 Node.js 20 和 npm：

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 build

API、Worker 和编译器在运行时仍依赖 PostgreSQL、Redis、共享存储和对应环境变量。

生产部署边界

本仓库的 Compose 文件用于本地开发和项目展示，不应原样作为生产配置。生产环境至少需要：

通过 Secret Manager、Docker Secrets 或受控环境变量注入凭据。
使用独立数据库账号、Redis 鉴权、TLS 和最小权限网络策略。
将对象存储、支付证书和短信凭据放在仓库之外。
关闭 Mock 短信和 Mock 支付入口。
对模型调用设置预算、速率限制、超时、重试和审计告警。
在反向代理层配置真实域名、HTTPS、安全响应头和上传限制。

安全与授权

生产 .env、数据库转储、真实手机号、论文数据和支付数据不在本仓库中。
compose/env/.env.dev、证书、日志、生成论文和本地存储目录已被 Git 忽略。
商业系统字体未进入公开仓库，LaTeX 容器使用 Noto CJK 与 TeX Gyre 字体。
前端的真实 ICP/公安备案号、客服账号、公司主体和生产域名已移除。
政策版本与用户同意记录能力仍被保留，但真实用户协议和隐私文本存储在私有数据库中，不在本仓库内。
安全问题处理方式见 SECURITY.md。
项目自有代码用于个人项目展示和技术评审，具体条款见 LICENSE。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.tooling		.tooling
apps		apps
compose		compose
docs		docs
proxy		proxy
scripts		scripts
.gitignore		.gitignore
.npmrc		.npmrc
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
prisma-reconcile.sh		prisma-reconcile.sh

Navigation Menu

Repository files navigation

沐光 Paper

核心能力

技术栈

系统架构

使用 Docker 的开发构建

1. 环境要求

2. 克隆并初始化配置

3. 检查环境变量和 Compose

4. 明确执行 Docker 开发构建

5. 启动服务并部署数据库迁移

6. 访问与日志

环境变量生效边界

不使用 Docker 的构建验证

生产部署边界

安全与授权

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

沐光 Paper

核心能力

技术栈

系统架构

使用 Docker 的开发构建

1. 环境要求

2. 克隆并初始化配置

3. 检查环境变量和 Compose

4. 明确执行 Docker 开发构建

5. 启动服务并部署数据库迁移

6. 访问与日志

环境变量生效边界

不使用 Docker 的构建验证

生产部署边界

安全与授权

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages