wenchuanyi/deploy/IIS部署与FTP发布.md

文传易 · IIS 部署与 FTP 发布手册

目标环境：Windows Server + IIS 10 + .NET 8 Hosting Bundle 站点地址：https://wenchuanyi.bbitcn.net 发布方式：FTP（ftp://116.198.221.125，默认端口 21，用户 wenchuanyi）

当前状态（2026-08-23）：本地全流程已通过冒烟测试—— 上传（共享/私密/标签，含 200MB 拦截）→ 二维码与取件码 → 取件查询/下载（计数）→ 标签列表 → 管理列表（含上传 IP）/删除，均已验证；数据库表已建、OSS 真实凭据已写入 appsettings.json（该文件不入库）。服务器上首次发布后，建议用手机微信扫码访问正式站再做一轮真机验证（含微信聊天记录选文件）。

---

1. 部署架构

浏览器
  │  https://wenchuanyi.bbitcn.net
  ▼
IIS 站点（物理路径 = 站点根目录）
  ├── index.html / assets/*        ← 前端 dist 构建产物
  ├── web.config                   ← 由 dotnet publish 自动生成（ANCM InProcess）
  ├── WenChuanyi.Api.dll           ← 后端发布输出
  └── appsettings.json             ← 数据库连接串 / OSS 凭据 / 上传限制

• 前端静态资源与后端发布输出放在同一 IIS 站点物理路径（默认文件夹或 wwwroot）。
• 后端 UseStaticFiles 提供前端静态文件，MapFallbackToFile("index.html") 兜底 SPA 路由； /api 与 /api/open 由 ASP.NET Core Module（ANCM）直接处理。
• 站点根目录布局见上；后端发布产物全部文件与前端 dist/ 内容合并进同一目录。

---

2. 服务器一次性准备（首次部署前）

1. 安装 .NET 8 Hosting Bundle
   • 下载：https://dotnet.microsoft.com/download/dotnet/8.0（选择 Hosting Bundle）
   • 安装后 IIS 中会出现 ASP.NET Core Module v2。
2. 创建 IIS 站点
   • IIS → 右键「网站」→ 添加网站；
   • 站点名称：wenchuanyi；
   • 物理路径：D:\wenchuanyi（或任意磁盘，站点根目录）；
   • 端口 80（HTTP）→ 后续绑定 443 + 证书，域名 wenchuanyi.bbitcn.net；
   • 应用程序池：.NET CLR 版本选「无托管代码」（InProcess 托管由 ANCM 处理）。
3. HTTPS 证书：为 wenchuanyi.bbitcn.net 绑定 SSL 证书（企业已有证书或申请免费证书）。
4. 防火墙：放行 80 / 443（及测试期 5280）。

排障：若站点 502.5 / 500.30，临时开启 web.config 中的 stdoutLogEnabled="true" 查看 stdoutLog 输出。

---

3. 构建发布包（开发机执行）

3.1 后端

cd backend/WenChuanyi.Api
dotnet publish -c Release

• 输出目录：bin/Release/net8.0/publish/
• Framework-dependent 模式，web.config 自动生成（hostingModel="inprocess"）。
• 发布前确认 appsettings.json 已配置真实凭据（见第 4 节）。

3.2 前端

cd frontend
npm install        # 首次
npm run build

• 输出目录：frontend/dist/（index.html + assets/*）。
• 构建目标 ES2018，兼容微信 X5 内核。

---

4. 敏感配置（appsettings.json）

backend/WenChuanyi.Api/appsettings.json 中需填写真实值，该文件已在 .gitignore 中，不会入库：

配置节	键	说明
ConnectionStrings:MySql	Password	数据库密码（r7P^f*v7rFts）
Oss	AccessKeyId	阿里云 OSS AK
Oss	AccessKeySecret	阿里云 OSS SK
OpenApi	UploadRoot	公开 API 可读取的服务端目录白名单
App	BaseUrl	站点地址，用于生成取件页链接（默认 https://wenchuanyi.bbitcn.net）

• 连接串密码含 ^、*，不含 ; / =，无需特殊转义，JSON 原样写入即可。
• 模板参考：appsettings.example.json（占位符 YOUR_DB_PASSWORD / YOUR_ACCESS_KEY_ID / YOUR_ACCESS_KEY_SECRET）。

---

5. FTP 发布

5.1 手动发布

用任意 FTP 客户端（FileZilla / WinSCP 等，被动模式）登录：

• 主机：116.198.221.125
• 端口：21
• 用户：wenchuanyi
• 密码：同数据库密码

上传清单（目标 = IIS 站点根目录，如 D:\wenchuanyi）：

前端 dist/ 全部文件                    → 站点根目录
后端 bin/Release/net8.0/publish/*      → 站点根目录（覆盖）

注意：web.config、appsettings.json 等必须位于站点根目录，勿放入子文件夹。

5.2 一键脚本发布

已提供 deploy/publish.ps1，一条命令完成「后端 publish + 前端 build + FTP 上传」：

powershell -ExecutionPolicy Bypass -File deploy/publish.ps1

5.3 发布后生效

• FTP 上传完成后，回收应用程序池使新版本生效：
  • IIS 管理器 → 应用程序池 → wenchuanyi → 右键「回收」；
  • 或命令行：C:\Windows\System32\inetsrv\appcmd recycle apppool /apppool.name:wenchuanyi
• 浏览器验证 https://wenchuanyi.bbitcn.net：
  1. 首页正常显示；
  2. /#/pickup、/#/admin 路由可访问（hash 路由不受 IIS 影响）；
  3. 上传一个测试文件 → 得到取件码 → 取件页下载成功 → 管理码列表可见。

---

6. 验证清单

项	验证方式	预期
首页静态资源	访问 /	页面正常渲染，无 404
SPA 路由	访问 /#/pickup	取件页正常（hash 路由不受 IIS 影响）
API	GET /api/open/download/000000	返回 JSON（凭证不存在提示），非 404
上传下载	上传 → 取件 → 下载	全流程通过，文件名还原
在线预览	文本/PDF/图片/音视频	预览正常
清理任务	查看日志	每 30 分钟扫描，无异常报错

---

7. 常见问题

现象	原因与处理
502.5 / 500.30	Hosting Bundle 未装或版本不匹配；或 appsettings.json 语法错误。检查事件查看器与 stdoutLog。
403.14	站点根目录无默认文档且 ANCM 未接管——确认 web.config 在站点根目录。
404 静态资源	前端产物未上传到站点根目录，或未启用 UseStaticFiles。
API 连接 MySQL 失败	服务器 3306 未放行 / 白名单未加服务器出口 IP。
上传 OSS 失败	OSS AK/SK 未填或权限不足；确认 Bucket bbit-f8-web 有 Put/Get/Delete 权限。
修改不生效	上传后未回收应用程序池。

---

8. 安全提示

• appsettings.json 含数据库密码与 OSS 凭据，不要上传到代码仓库 / 不要外传（已在 .gitignore）。
• FTP 凭据仅运维持有，建议定期轮换。
• 日志不会打印 OSS 凭据、数据库密码与文件内容明文。