MSERP FastAPI 项目

群晖 Docker 演示站点部署操作文档（标准版）

一、目标与约定

目标

• 在 群晖 Docker 中部署 MSERP FastAPI 演示站点
• 支持 Git 仓库更新后快速重建
• 本地开发 / Docker / 生产环境路径一致
• 静态资源、上传文件 可正常访问且可持久化

关键约定

• 不修改现有 Python 业务代码
• www.py 中路径定义保持不变：

app.mount("/assets", StaticFiles(directory="app/assets"), name="assets")
app.mount("/files", StaticFiles(directory="files"), name="files")

二、项目结构约定（最终正确结构）

Git 仓库结构（本地 & 容器内）

MSERP/
├─ app/
│  └─ assets/           # 前端静态资源
├─ files/               # 上传/导出文件目录（与 app 同级）
│  └─ .gitkeep          # 占位，确保 Git 提交
├─ main.py
├─ www.py
├─ requirements.txt
├─ Dockerfile

⚠️ Git 不提交空目录，files/ 必须放 .gitkeep

三、Dockerfile（项目根目录）

位置：MSERP/Dockerfile

FROM python:3.10-slim

WORKDIR /app

# 确保 files 目录存在（即使 volume 未挂载也不炸）
RUN mkdir -p files

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

COPY . .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

说明：

• WORKDIR /app
• directory="files" → /app/files
• directory="app/assets" → /app/app/assets
• 启动方式 不走 if __name__ == "__main__"

四、群晖目录规划

宿主机目录

/volume1/docker/mserppy-demo/
├─ docker-compose.yml
├─ MSERP/               # Git 仓库代码
└─ files/               # 上传文件持久化目录（宿主机）

五、docker-compose.yml（群晖）

位置：/volume1/docker/mserppy-demo/docker-compose.yml

services:
  mserp_demo:
    container_name: mserp_demo_app
    build:
      context: ./MSERP
    ports:
      - "18080:8000"
    volumes:
      - /volume1/docker/mserppy-demo/files:/app/files
    restart: unless-stopped

说明：

• 不写 dockerfile 路径（默认使用 context 内的 Dockerfile）
• /files 挂载到 /app/files，保证上传文件不丢
• assets 由镜像内 COPY . . 提供，不需要 volume

六、首次部署流程（群晖）

1️⃣ 安装 Git（一次性）

DSM → 套件中心 → 安装 Git Server

验证：

git --version

2️⃣ 拉取代码

cd /volume1/docker
mkdir -p mserppy-demo
cd mserppy-demo
git clone http://你的Gitea地址/你的用户/MSERP.git

3️⃣ 创建宿主机 files 目录

mkdir -p /volume1/docker/mserppy-demo/files

4️⃣ 构建并启动

cd /volume1/docker/mserppy-demo
docker compose up -d --build

5️⃣ 验证

docker ps
docker logs mserp_demo_app

成功标志：

Uvicorn running on http://0.0.0.0:8000

访问：

http://群晖IP:18080
http://你的域名:18080

七、静态资源与上传文件验证

1️⃣ 验证静态资源

curl -I http://127.0.0.1:18080/assets/css/public.css

返回 200 / 304 即正常。

⚠️ Linux 大小写敏感
public.css ≠ Public.css
前端静态文件名 必须统一小写。

2️⃣ 验证上传目录

echo ok > /volume1/docker/mserppy-demo/files/test.txt
curl http://127.0.0.1:18080/files/test.txt

返回 ok 即正常。

八、Windows（PyCharm）提交大小写修复（必读）

问题背景

Windows 文件系统大小写不敏感，Git 默认忽略大小写变更。

正确处理方式（推荐）

在 PyCharm Terminal（仓库根目录） 执行：

git config core.ignorecase false
git rm -r --cached .
git add .
git commit -m "chore: rescan working tree for case-sensitive files"
git push

然后在群晖：

cd /volume1/docker/mserppy-demo/MSERP
git pull
cd ..
docker compose up -d --build

九、后续更新流程（标准）

以后每次更新，只需：

cd /volume1/docker/msconsole
sh /volume1/docker/msconsole/update.sh


cd /volume1/docker/mserppy-demo
sh /volume1/docker/mserppy-demo/update.sh


cd /volume1/docker/msrollopt
sh /volume1/docker/msrollopt/update.sh

口诀：
拉代码 → 重建 → 自动重启

十、关键经验总结（必看）

1. Docker 是 Linux，大小写敏感
2. StaticFiles(directory=...) 使用的是 工作目录相对路径
3. Git 不提交空目录 → .gitkeep
4. 上传文件一定要用 volume 持久化
5. Dockerfile 必须提交到仓库
6. 本地 OK ≠ Docker OK，一切以容器为准