Windows 10 云服务器部署文档

目标环境：Windows 10 云服务器，Caddy 监听 80 端口，Next.js 监听 127.0.0.1:3000，FastAPI 监听 127.0.0.1:8000。

1. 本地开发

启动后端：

cd C:\Users\Administrator\Desktop\personal-portfolio-website\backend
python -m venv venv
venv\Scripts\pip install -r requirements.txt
Copy-Item .env.example .env
venv\Scripts\python create_admin.py
venv\Scripts\python start_prod.py

启动前端：

cd C:\Users\Administrator\Desktop\personal-portfolio-website\frontend
npm install
npm run dev

浏览器访问 http://localhost:3000/zh。

2. 清理环境

打包前清理脏的 NODE_ENV，不要手动设置 NODE_ENV，由 Next.js 自动识别开发或生产模式。

cd C:\Users\Administrator\Desktop\personal-portfolio-website
.\scripts\clear-node-env.ps1

如果怀疑前端依赖污染，执行纯净重装：

cd C:\Users\Administrator\Desktop\personal-portfolio-website\frontend
Remove-Item -Recurse -Force node_modules, .next -ErrorAction SilentlyContinue
npm cache verify
npm ci

3. 后端生产运行

编辑 backend\.env：

DEBUG=false
SECRET_KEY=<替换为随机密钥>
DATABASE_URL=sqlite:///C:/Administrator/Desktop/personal-portfolio-website/backend/portfolio.db
UPLOAD_DIR=C:/Administrator/Desktop/personal-portfolio-website/backend/uploads
CORS_ORIGINS=["http://yulinfeng.cn","http://www.yulinfeng.cn","http://localhost:3000"]

手动启动后端：

cd C:\Users\Administrator\Desktop\personal-portfolio-website
.\scripts\start-backend.ps1 -ProjectRoot C:\Users\Administrator\Desktop\personal-portfolio-website

后端只监听 127.0.0.1:8000，不在安全组或防火墙中对外开放 8000。

4. 前端生产运行

确认 frontend\.env.production：

BACKEND_URL=http://127.0.0.1:8000
NEXT_PUBLIC_BACKEND_URL=
NEXT_PUBLIC_API_URL=

打包并启动前端：

cd C:\Users\Administrator\Desktop\personal-portfolio-website
.\scripts\start-frontend.ps1 -ProjectRoot C:\Users\Administrator\Desktop\personal-portfolio-website

前端只监听 127.0.0.1:3000，不要在安全组或防火墙中对外开放 3000。

5. Caddy 反向代理

安装 Caddy for Windows 后复制项目配置：

New-Item -ItemType Directory -Force C:\Caddy
Copy-Item C:\Users\Administrator\Desktop\personal-portfolio-website\caddy\Caddyfile C:\Caddy\Caddyfile
cd C:\Caddy
caddy validate --config Caddyfile
.\caddy.exe run --config Caddyfile

长期运行时注册为 Windows 服务：

caddy service install --config C:\Caddy\Caddyfile
Start-Service caddy

Caddy 转发规则：

/api/v1/*  -> 127.0.0.1:8000
/uploads/* -> 127.0.0.1:8000
/*         -> 127.0.0.1:3000

6. 防火墙和安全组

Windows 防火墙只放行公网 HTTP：

New-NetFirewallRule -DisplayName "Portfolio HTTP 80" -Direction Inbound -Protocol TCP -LocalPort 80 -Action Allow

云服务器安全组：

允许 TCP 80 来源 0.0.0.0/0
不开放 TCP 3000
不开放 TCP 8000