千千模岛 API 文档
DEPLOYMENT

部署到宝塔面板

将千模岛 API 文档网站构建为静态文件，并部署到宝塔面板。

#前置要求

  • 已安装宝塔面板（Linux 或 Windows 版本）
  • 服务器已通过宝塔软件商店安装 Node.js
  • 准备一个域名；也可以直接使用服务器 IP 访问

#部署步骤

#步骤 1：在本地构建项目

进入项目目录，安装依赖并构建生产版本：

bash
cd "你的项目目录"
npm install
npm run build

构建完成后，静态文件位于 docs/.vitepress/dist 目录。

#步骤 2：上传文件到服务器

#方法 1：使用宝塔面板文件管理器

  1. 登录宝塔面板，打开左侧“文件”。
  2. 进入网站根目录，例如 /www/wwwroot/你的域名。
  3. 上传 docs/.vitepress/dist 目录内的全部文件。

#方法 2：使用 FTP/SFTP

bash
# Linux / macOS 可使用 scp
scp -r docs/.vitepress/dist/* root@你的服务器IP:/www/wwwroot/你的域名/

# 也可以使用 FileZilla、WinSCP 等工具上传

#步骤 3：在宝塔面板创建网站

  1. 打开“网站”，点击“添加站点”。
  2. 域名填写你的域名或服务器 IP。
  3. 根目录选择刚才上传文件的目录。
  4. FTP 与数据库均选择不创建，PHP 版本选择纯静态。
  5. 提交创建站点。

#步骤 4：配置网站设置

#配置伪静态（重要）

打开网站“设置 → 伪静态”，选择自定义或 Vue，并填写：

nginx
location / {
  try_files $uri $uri/ /index.html;
}

#配置 SSL 证书（推荐）

  1. 在网站设置中打开“SSL”。
  2. 选择 Let's Encrypt 免费证书并勾选域名。
  3. 申请成功后开启强制 HTTPS。

#步骤 5：验证部署

访问你的域名或服务器 IP，应当可以看到文档网站首页，例如：

  • https://docs.你的域名.com
  • http://你的服务器IP

#自动化部署（可选）

#方法 1：使用 Git 自动部署

在宝塔面板安装 Git 插件，然后在服务器克隆并构建项目：

bash
cd /www/wwwroot
git clone https://github.com/你的用户名/你的仓库.git 你的域名
cd 你的域名
npm install
npm run build

创建 deploy.sh：

bash
#!/bin/bash
cd /www/wwwroot/你的域名
git pull
npm install
npm run build
cp -r docs/.vitepress/dist/* /www/wwwroot/你的域名/

随后可以通过定时任务或 Webhook 执行该脚本。

#方法 2：使用宝塔计划任务

  1. 在宝塔面板打开“计划任务”。
  2. 添加 Shell 脚本任务，并填入上面的部署脚本。
  3. 设置执行周期，例如每天凌晨执行。

#性能优化

#1. 启用 Gzip 压缩

在 Nginx 的 http 或 server 块加入：

nginx
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/javascript application/json;

保存配置并重启 Nginx。

#2. 启用浏览器缓存

nginx
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
  expires 30d;
  add_header Cache-Control "public, immutable";
}

#3. 配置 CDN（可选）

  • 在宝塔面板安装 CDN 加速插件。
  • 也可以使用阿里云、腾讯云或 Cloudflare 等第三方 CDN。
  • 将 JavaScript、CSS、图片等静态资源交由 CDN 分发。

#故障排除

#问题：404 错误

原因：伪静态规则未配置。
解决：按照步骤 4 设置伪静态规则。

#问题：页面样式丢失

原因：静态资源路径错误。
解决：检查 config.mts 中的 base；部署在子目录时，应设置为 base: '/子目录/'。

#问题：无法访问

原因：防火墙或云服务器安全组未开放端口。
解决：在宝塔“安全”和云服务器安全组中开放 80、443 端口。

#问题：SSL 证书申请失败

原因：域名解析不正确或 80 端口不可访问。

  • 确认域名 A 记录指向服务器 IP。
  • 确认 80 端口已开放。
  • 申请证书前暂时关闭 CDN。

#更新网站

  1. 在本地修改文档。
  2. 运行 npm run build 重新构建。
  3. 将 docs/.vitepress/dist 中的文件重新上传到服务器。
  4. 也可以运行前述自动化部署脚本。

#监控和维护

#查看访问日志

在宝塔面板中打开“网站设置 → 日志”，查看访问日志和错误日志。

#设置流量监控

可以安装“网站监控报表”插件，查看访问统计与流量使用情况。

#安全建议

  • 定期更新宝塔面板和服务器系统。
  • 修改宝塔面板默认的 8888 端口。
  • 启用防火墙，只开放必要端口。
  • 按需安装宝塔 WAF 防火墙插件。
  • 为网站文件设置定期自动备份。

#总结

  • 纯静态站点，不需要后端服务
  • 加载速度快，维护和更新方便
  • 支持 HTTPS 加密
  • 适合搜索引擎收录
提示
遇到部署问题时，可先查看“网站设置 → 日志 → 错误日志”。
本页目录前置要求