# Windows 10 云服务器部署文档

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

## 1. 本地开发

启动后端：

```powershell
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
```

启动前端：

```powershell
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 自动识别开发或生产模式。

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

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

```powershell
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`：

```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"]
```

手动启动后端：

```powershell
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`：

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

打包并启动前端：

```powershell
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 后复制项目配置：

```powershell
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 服务：

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

Caddy 转发规则：

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

## 6. 防火墙和安全组

Windows 防火墙只放行公网 HTTP：

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

云服务器安全组：

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

## 7. 桌面定时程序共存

保留 Windows 图形环境和自研桌面定时程序。网站部署只占用 `80`、`3000`、`8000` 端口，不需要 Linux、WSL、Docker 或无桌面环境。

## 8. 验证命令

```powershell
Invoke-WebRequest http://127.0.0.1:8000/api/v1/health -UseBasicParsing
Invoke-WebRequest http://127.0.0.1:3000/zh -UseBasicParsing
Invoke-WebRequest http://yulinfeng.cn/zh -UseBasicParsing
Invoke-WebRequest http://yulinfeng.cn/api/v1/health -UseBasicParsing
```

查看日志：

```powershell
Get-Content C:\Users\Administrator\Desktop\personal-portfolio-website\logs\backend_error.log -Tail 100
Get-Content C:\Users\Administrator\Desktop\personal-portfolio-website\logs\frontend_error.log -Tail 100
```
```powershell
Get-Content C:\Users\Administrator\Desktop\personal-portfolio-website\logs\frontend_error.log -Tail 100
```
后端实时日志：
```powershell
Get-Content "C:\Users\Administrator\Desktop\personal-portfolio-website\logs\backend_error.log" -Wait
```
```powershell
Get-Content "C:\Users\Administrator\Desktop\personal-portfolio-website\logs\frontend_error.log" -Wait
```

Caddy 服务日志可通过 Windows 事件查看器查看；排查时也可以临时在终端执行 `caddy run --config C:\Caddy\Caddyfile`。