FireflyBlog + blogspring 前后端联调完整指南

服务清单#

域名 DNS 配置#

注意：两个域名都通过 Cloudflare 代理，SSL 模式设为 Flexible（Cloudflare 处理 HTTPS，到源站走 HTTP）。

服务器信息#

SSH 连接配置#

1
# 在本地终端执行（会提示输入密码）
2
ssh root@47.104.152.119
3

4
# 登录后执行以下命令设置公钥
5
mkdir -p ~/.ssh && chmod 700 ~/.ssh
6
echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKELbP3RHgJrLDl7sZEtMWwB6fTYKXfgCwBU5zIDmc0/ 2860556024@qq.com' >> ~/.ssh/authorized_keys
7
chmod 600 ~/.ssh/authorized_keys

1
ssh root@47.104.152.119

阿里云安全组配置#

在 ECS 控制台 → 实例详情 → 安全组 → 入方向添加规则：

服务器目录结构#

1
/opt/
2
├── portfolio-backend.jar          # Spring Boot JAR 包 (84MB)
3
└── portfolio/
4
    ├── application.yml            # 应用配置文件
5
    └── storage/
6
        ├── data/
7
        │   └── portfolio.db       # SQLite 数据库
8
        └── media/                  # 上传的媒体文件

已安装软件#

1. 构建 JAR 包#

在本地 Windows 环境：

1
cd E:/blogspring/backend
2
mvn clean package -DskipTests

产物路径：E:/blogspring/backend/target/portfolio-backend-0.1.0-SNAPSHOT.jar

2. 上传到服务器#

1
scp E:/blogspring/backend/target/portfolio-backend-0.1.0-SNAPSHOT.jar root@47.104.152.119:/opt/portfolio-backend.jar

3. 创建配置文件#

在服务器上创建 /opt/portfolio/application.yml：

1
server:
2
  port: ${PORT:8080}
3

4
spring:
5
  datasource:
6
    url: jdbc:sqlite:/opt/portfolio/storage/data/portfolio.db
7
    driver-class-name: org.sqlite.JDBC
8
  jpa:
9
    open-in-view: false
10
    hibernate:
11
      ddl-auto: update
12
    properties:
13
      hibernate:
14
        dialect: org.hibernate.community.dialect.SQLiteDialect
15
        format_sql: true
16
  servlet:
17
    multipart:
18
      max-file-size: 50MB
19
      max-request-size: 50MB
20

21
content:
22
  storage-root: /opt/portfolio/storage/media
23
  media-base-url: https://api.f3f3.top/api/files
24
  admin-token: my-secret-token-2024
25
  allowed-origins:
26
    - https://f3f3.top
27
    - https://api.f3f3.top
28

29
logging:
30
  level:
31
    root: INFO
32
    org.hibernate.SQL: WARN

4. 创建 systemd 服务#

创建 /etc/systemd/system/portfolio.service：

1
[Unit]
2
Description=Portfolio Backend API
3
After=network.target
4

5
[Service]
6
Type=simple
7
User=root
8
WorkingDirectory=/opt/portfolio
9
ExecStart=/usr/bin/java -Xms256m -Xmx512m -jar /opt/portfolio-backend.jar --spring.config.additional-location=/opt/portfolio/application.yml
10
Restart=on-failure
11
RestartSec=10
12

13
[Install]
14
WantedBy=multi-user.target

启动服务：

1
systemctl daemon-reload
2
systemctl enable portfolio
3
systemctl start portfolio
4
systemctl status portfolio

5. 配置 Nginx 反向代理#

创建 /etc/nginx/sites-available/api.f3f3.top：

1
server {
2
    listen 80;
3
    listen 443 ssl;
4
    server_name api.f3f3.top;
5

6
    ssl_certificate /etc/letsencrypt/live/api.f3f3.top/fullchain.pem;
7
    ssl_certificate_key /etc/letsencrypt/live/api.f3f3.top/privkey.pem;
8
    include /etc/letsencrypt/options-ssl-nginx.conf;
9
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
10

11
    client_max_body_size 50M;
12

13
    location / {
14
        proxy_pass http://127.0.0.1:8080;
15
        proxy_set_header Host $host;
16
        proxy_set_header X-Real-IP $remote_addr;
17
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
18
        proxy_set_header X-Forwarded-Proto $scheme;
19
    }
20
}

启用配置：

1
ln -sf /etc/nginx/sites-available/api.f3f3.top /etc/nginx/sites-enabled/
2
nginx -t
3
systemctl reload nginx

6. 配置 SSL 证书#

1
certbot --nginx -d api.f3f3.top --non-interactive --agree-tos --email 2860556024@qq.com

注意：如果使用 Cloudflare Flexible 模式，Nginx 配置中 HTTP 不要重定向到 HTTPS，否则会造成重定向循环。

修复后 Nginx 配置要点：

• 同时监听 80 和 443 端口
• 不设置 return 301 https://... 重定向
• 直接代理到后端

Vercel 部署#

1
cd E:/Astro/FireflyBlog
2
vercel --prod --yes

关键配置文件#

1
PUBLIC_API_BASE_URL=https://api.f3f3.top

1
const apiBase = (import.meta.env.PUBLIC_API_BASE_URL || '').replace(/\/$/, '');
2

3
function getBaseUrl(): string {
4
  if (apiBase) return apiBase;
5
  if (typeof window !== 'undefined') return window.location.origin;
6
  return 'http://localhost:4321';
7
}
8

9
const base = getBaseUrl();
10

11
export const runtimeConfig = {
12
  apiBaseUrl: base,
13
  publicApiBaseUrl: `${base}/api`,
14
  adminApiBaseUrl: `${base}/api`,
15
  mediaBaseUrl: `${base}/api/media`,
16
};

SSR 模式下的 Prerender 问题#

Astro output: "server" 模式下，使用 getStaticPaths() 的页面必须添加 export const prerender = true;，否则会报 TypeError: Cannot read properties of undefined。

需要添加的文件：

1
// src/pages/[...page].astro（首页/分页）
2
export const prerender = true;
3

4
// src/pages/posts/[...slug].astro（文章详情）
5
export const prerender = true;
6

7
// src/pages/gallery/[album].astro（相册）
8
export const prerender = true;

原因：SSR 模式下 getStaticPaths() 被忽略，Astro.props.page 为 undefined。

Media 上传代理路由#

文件：src/pages/api/media/upload.ts

1
import type { APIRoute } from "astro";
2

3
export const POST: APIRoute = async ({ request }) => {
4
  const backendBase = (import.meta.env.PUBLIC_API_BASE_URL || "").replace(/\/$/, "");
5
  if (!backendBase) {
6
    return new Response("PUBLIC_API_BASE_URL is not configured", { status: 500 });
7
  }
8

9
  const token = request.headers.get("x-admin-token");
10
  if (!token) {
11
    return new Response("Missing X-ADMIN-TOKEN header", { status: 401 });
12
  }
13

14
  const formData = await request.formData();
15

16
  const upstream = await fetch(`${backendBase}/api/admin/media/upload`, {
17
    method: "POST",
18
    headers: { "X-ADMIN-TOKEN": token },
19
    body: formData,
20
  });
21

22
  const body = await upstream.text();
23
  return new Response(body, {
24
    status: upstream.status,
25
    headers: { "Content-Type": "application/json" },
26
  });
27
};

请求链路：

1
Admin 页面 → /api/media/upload (Astro 代理) → api.f3f3.top/api/admin/media/upload (Spring Boot)

Admin Dashboard Token 修复#

src/scripts/admin-dashboard.ts 中的上传请求必须携带 Token：

1
// 修复前（缺少 X-ADMIN-TOKEN header）
2
const response = await fetch(`${runtimeConfig.adminApiBaseUrl}/media/upload`, {
3
  method: "POST",
4
  body: formData
5
});
6

7
// 修复后
8
const response = await fetch(`${runtimeConfig.adminApiBaseUrl}/media/upload`, {
9
  method: "POST",
10
  headers: { "X-ADMIN-TOKEN": state.token },
11
  body: formData
12
});

API 对照表#

前端 apiClient.ts 调用路径 → 后端 Spring Boot 端点：

Admin API 对照表#

后端实体类型#

1
export type Project = {
2
  id: number;
3
  title: string;
4
  description?: string;
5
  link: string;
6
  coverImageUrl?: string;
7
  videoUrl?: string;
8
  tags?: string[];
9
  featured?: boolean;
10
  published?: boolean;
11
  sortOrder?: number;
12
};
13

14
export type BlogPost = {
15
  id: number;
16
  title: string;
17
  slug: string;
18
  summary?: string;
19
  content?: string;
20
  contentHtml?: string;
21
  headings?: { slug: string; text: string; depth: number }[];
22
  coverImageUrl?: string;
23
  publishDate: string;
24
  featured?: boolean;
25
  tags?: string[];
26
};
27

28
export type Profile = {
29
  id: number;
30
  fullName: string;
31
  headline?: string;
32
  bio?: string;
33
  email?: string;
34
  phone?: string;
35
  wechat?: string;
36
  location?: string;
37
  jobTitle?: string;
38
  heroImageUrl?: string;
39
  resumeUrl?: string;
40
  primaryCtaLabel?: string;
41
  primaryCtaLink?: string;
42
  secondaryCtaLabel?: string;
43
  secondaryCtaLink?: string;
44
  socialLinks?: Record<string, string>;
45
};
46

47
export type Work = {
48
  id: number;
49
  name: string;
50
  description?: string;
51
  url: string;
52
  imageUrl?: string;
53
  videoUrl?: string;
54
  tags?: string[];
55
  isShow?: boolean;
56
  sortOrder?: number;
57
};
58

59
export type MediaAsset = {
60
  id: number;
61
  originalFilename: string;
62
  relativePath: string;
63
  publicUrl: string;
64
  mimeType?: string;
65
  sizeInBytes?: number;
66
  category?: string;
67
};

服务器管理#

1
# SSH 连接
2
ssh root@47.104.152.119
3

4
# 查看 Java 服务状态
5
systemctl status portfolio
6

7
# 重启 Java 服务
8
systemctl restart portfolio
9

10
# 查看 Java 日志
11
journalctl -u portfolio -f
12

13
# 查看 Java 日志（最近 50 行）
14
journalctl -u portfolio -n 50
15

16
# 停止服务
17
systemctl stop portfolio
18

19
# 查看 Nginx 状态
20
systemctl status nginx
21

22
# 重启 Nginx
23
systemctl restart nginx
24

25
# 测试 Nginx 配置
26
nginx -t
27

28
# 查看 Nginx 错误日志
29
tail -f /var/log/nginx/error.log

本地构建和部署#

1
# 构建后端 JAR
2
cd E:/blogspring/backend
3
mvn clean package -DskipTests
4

5
# 上传到服务器
6
scp E:/blogspring/backend/target/portfolio-backend-0.1.0-SNAPSHOT.jar root@47.104.152.119:/opt/portfolio-backend.jar
7

8
# 在服务器上重启服务
9
ssh root@47.104.152.119 "systemctl restart portfolio"
10

11
# 部署前端到 Vercel
12
cd E:/Astro/FireflyBlog
13
vercel --prod --yes
14

15
# 查看 Vercel 部署状态
16
vercel ls
17

18
# 查看 Vercel 部署日志
19
vercel logs f3f3.top --limit 20

API 测试#

1
# 测试后端 API（本地）
2
curl http://localhost:8080/api/public/profile
3

4
# 测试后端 API（公网）
5
curl https://api.f3f3.top/api/public/profile
6

7
# 测试前端
8
curl -I https://f3f3.top/
9

10
# 测试完整链路
11
curl https://api.f3f3.top/api/public/projects
12
curl https://api.f3f3.top/api/public/blog-posts

数据库操作#

1
# 连接到 SQLite 数据库
2
sqlite3 /opt/portfolio/storage/data/portfolio.db
3

4
# 查看所有表
5
.tables
6

7
# 查看表结构
8
.schema
9

10
# 查看数据
11
SELECT * FROM blog_posts;
12
SELECT * FROM projects;
13

14
# 退出
15
.quit

首页 500 错误#

现象：f3f3.top 返回 500，其他页面正常

原因：[...page].astro 缺少 export const prerender = true;

解决：在 src/pages/[...page].astro 顶部添加 export const prerender = true;

api.f3f3.top 返回 522#

现象：Cloudflare 返回 522 Connection Timed Out

原因：阿里云安全组未放行端口 80/443

解决：在 ECS 安全组入方向添加 TCP 80 和 443 规则

api.f3f3.top 返回 404 DEPLOYMENT_NOT_FOUND#

现象：Vercel 返回 404

原因：域名没有指向正确的部署

解决：确保 Cloudflare DNS 的 A 记录指向 47.104.152.119

媒体上传失败#

现象：管理后台上传文件报错

原因：

1. X-ADMIN-TOKEN header 未携带
2. 后端 api.f3f3.top 未部署
3. Token 不匹配

解决：

1. 检查 src/scripts/admin-dashboard.ts 中上传请求是否有 headers: { "X-ADMIN-TOKEN": state.token }
2. 确认后端服务运行中：systemctl status portfolio
3. 确认 Token 一致：application.yml 中的 admin-token 与管理后台输入的相同

SSL 证书申请失败#

现象：certbot 报 unauthorized 错误

原因：Cloudflare 代理导致 ACME 验证不通

解决：Cloudflare Flexible 模式下不申请证书也能用，Cloudflare 自动处理 HTTPS

Nginx 重定向循环#

现象：页面不断刷新，无法加载

原因：Nginx 配置了 HTTP→HTTPS 重定向，Cloudflare Flexible 模式下形成循环

解决：Nginx 同时监听 80 和 443，不设置 return 301 https://...

阿里云 ICP 备案拦截（403）#

现象：Cloudflare Flexible 模式下 api.f3f3.top 返回 403，页面显示”非备案拦截”

原因：阿里云要求所有域名完成 ICP 备案才能通过 80 端口（HTTP）访问。未备案时阿里云会拦截 HTTP 请求。

解决：

1. 申请 ICP 备案（推荐）：阿里云控制台 → 备案管理 → 添加域名 f3f3.top，备案通过后 80 端口正常
2. 临时方案：改用 Cloudflare Full 模式（走 443 端口，不受备案拦截），但需修复 Nginx SSL 配置

Cloudflare 525 SSL 握手失败#

现象：Cloudflare Full (Strict) 模式下 api.f3f3.top 返回 525

原因：Cloudflare 无法与源站建立 SSL 连接。可能原因：

1. 阿里云安全组未放行 443 端口
2. Nginx SSL 配置与 Cloudflare 不兼容
3. 证书链不完整

解决：

1. 确认安全组已放行 443 端口
2. 将 Cloudflare SSL 模式改为 Full（不是 Full Strict）
3. 检查 Nginx SSL 配置：openssl s_client -connect 47.104.152.119:443 -servername api.f3f3.top

1. Windows 构建 Symlink 问题#

本地 pnpm build 可能报 EPERM: operation not permitted, symlink 错误。这是 Windows 权限问题，不影响 Vercel 部署（Vercel 用 Linux 构建）。

2. Cloudflare Flexible 模式#

Cloudflare SSL 设为 Flexible 时：

• 用户 → Cloudflare（HTTPS）→ 源站（HTTP）
• 源站不需要 SSL 证书
• 但源站的 HTTP 响应会被 Cloudflare 转为 HTTPS 返回给用户

3. CORS 跨域#

如果前端和后端域名不同，后端需要配置 CORS：

1
// Spring Boot WebConfig.java
2
@Override
3
public void addCorsMappings(CorsRegistry registry) {
4
    registry.addMapping("/api/**")
5
        .allowedOrigins("https://f3f3.top", "https://api.f3f3.top")
6
        .allowedMethods("GET", "POST", "PUT", "DELETE")
7
        .allowedHeaders("*");
8
}

4. Service Worker 缓存#

Vercel 部署后如果页面不更新，可能是 Service Worker 缓存问题。在浏览器中：

1. 打开 DevTools → Application → Service Workers
2. 点击 Unregister
3. 或勾选 Update on reload