第 08 课：数据库与文件存储

你的应用看起来不错，也能处理错误。但它什么都保存不了，也没地方放用户想上传的文件。这节课就来解决这两件事。

---

现在，如果用户在你的应用里输入了什么，刷新页面就没了。如果想附张图片，根本没地方存。你的应用没有记忆，也没有存储空间。

数据库（database） 给你的应用一份记忆。文件存储（file storage） 给你的应用一个地方，去放那些不那么结构化的东西——图片、音频、视频、PDF。两者结合在一起，能把一个 demo 变成真正的产品。

我们会同时用 Supabase 来做这两件事。Supabase 是一项免费服务，开箱即用地提供数据库和文件存储。一个工具，两个问题一起解决。

安全是这一课的贯穿主题。 数据库和存储是攻击者最先盯上的地方——用户数据就放在那里。请留意每一处安全提示，不要跳过。在这里把基础打牢，是「会泄露用户数据的应用」和「不会泄露的应用」之间的分水岭。

---

什么是数据库？

数据库就是应用保存信息的地方。把它想成一张电子表格就行：应用可以读取其中的数据，也可以写入新的数据。

你用过的每一个应用背后都有一个数据库。Instagram 把你的配文、点赞和粉丝列表存在数据库里。Twitter 存推文。Spotify 存歌单。当你关掉应用再打开，东西还在——因为它们存在数据库里，不是只存在你的设备上。

如果没有数据库，你的应用就像一块白板。用的时候看着挺好，可一旦有人擦掉它（或者刷新页面），一切都没了。

数据库是怎么组织的

一个数据库由一组 表（table） 组成。每张表存放一种东西。如果你在做一个 Todo List 应用，可能会有：

• 一张 users 表（在用这个应用的人）
• 一张 todos 表（他们要做的事）
• 一张 projects 表（他们怎么组织自己的任务）

每张表都有 行（row） 和 列（column），就像电子表格一样。todos 表可能长这样：

id  user_id  task              completed
--  -------  ----------------  ---------
1   abc123   Buy groceries     false
2   abc123   Walk the dog      true
3   def456   Finish homework   false

一行代表一条记录，一列代表这条记录的一个字段。id 列给每一行一个唯一标识符，方便数据库找到它。

---

什么是 SQL？

数据库存放数据。SQL（读作「sequel」）就是你和数据库对话的语言。它代表 结构化查询语言（Structured Query Language），是地球上几乎所有主流数据库都说的语言：Postgres、MySQL、SQLite、Supabase（底层就是 Postgres），甚至包括 Google 的内部系统。

这一课里你会经常看到 SQL。你的 AI 智能体会把一段段 SQL 片段交给你，让你粘贴进 Supabase。看懂这些片段在做什么，能让你从「闭着眼睛运行」变成「运行前先读懂命令」。这就是「会用工具」和「被工具牵着走」之间的区别。

SQL 出乎意料地易读。下面这四个命令覆盖了应用 90% 的工作：

• SELECT 读取行。「把属于用户 abc123 的任务都给我。」

  SELECT * FROM todos WHERE user_id = 'abc123';
  

• INSERT 添加一行。「给用户 abc123 加一条名叫 'Buy groceries' 的待办。」

  INSERT INTO todos (user_id, task) VALUES ('abc123', 'Buy groceries');
  

• UPDATE 修改已有的行。「把 #1 号待办标记为已完成。」

  UPDATE todos SET completed = true WHERE id = 1;
  

• DELETE 删除行。「删掉 #2 号待办。」

  DELETE FROM todos WHERE id = 2;
  

你的应用每天会上千次访问数据库，而每一次读写背后跑的都是这四种命令之一。你的 AI 智能体在替你写 SQL，你的任务是看到时能认得出来。

为什么值得学一点 SQL

哪怕你从不亲手写查询，了解一点 SQL 也很值得：

• 你能看懂智能体写的东西。 这条查询安全吗？有没有按正确的用户过滤？会不会删多？你至少能看出来大致有没有问题。
• 你能调试。 当应用里「什么都没显示」时，问题通常就藏在查询里。能打开 Supabase 的 SQL 编辑器自己跑一下查询，是一项很有用的技能。
• 它是长期资产。 SQL 已经做了 50 年的标准。框架来来去去，你今天学的 SQL 到 2050 年还能用。
• 它通用。 同样的查询能跑在 Postgres、MySQL、SQLite 以及几乎所有云数据库上。学一次，到处用。

你不需要变成专家。能认出上面那四个命令，就足够上完这一课和后面绝大部分内容了。

---

什么是文件存储？

数据库适合处理结构化数据（文本、数字、日期、各种关系），但不适合直接存原始文件。比如把一张 5MB 的照片放进数据库行里，读写都会变慢，备份成本也会上升，浏览器拿到文件也不够高效。

文件存储（file storage） 就是专门解决这个问题的。它提供一个云端存储空间，每个文件都有自己的 URL。应用上传文件后拿到路径，把路径存在数据库里；之后要显示文件时，再通过这个路径取回文件。

适合放进 storage 的内容包括：

• 头像和个人资料图片
• 用户上传的图片、视频、音频、PDF
• 各种导出文件、报表和生成文件

分工永远一样：元数据进数据库，文件字节进 storage，数据库里只保存一个指向这些字节的路径。

---

来构建一个清单应用

我们会从一个最小但确实需要数据库的例子开始：一个清单。你通过输入框添加条目，通过删除按钮移除条目。刷新页面后，清单仍然存在。这就是数据库带来的能力。

---

给你的应用加上 Storage

接下来，让用户能够上传文件——比如给每条清单条目附上一张图片。

创建一个 Bucket

在 Supabase Storage 里，bucket（桶） 是一个有名字的文件容器，类似一个顶层文件夹。通常每一类内容会单独放在一个 bucket 里：avatars、post-images、documents。

1. 在 Supabase 控制台里，点击侧栏的 Storage

2. 点击 New bucket

   

3. 把它命名为 todo-attachments

4. 暂时保持 Public bucket 关闭

5. 点 Save

安全——public bucket 与 private bucket。 public bucket 里的所有文件，只要拿到 URL，任何人都能读取。如果内容本来就应该公开（比如社交应用里的头像），这样没问题。private bucket 则要求拥有者的会话才能读取。任何用户期望保持私密的内容（收据、医疗资料、消息附件）都应该使用 private bucket。默认设为 private。只有在你确实想公开内容时才打开 public。

设置一条 Storage 策略

bucket 和表一样，也使用类似 RLS 的策略机制。你现在还没有鉴权，所以先设置一条宽松的策略，让上传流程能跑起来；后面再把它收紧：

1. 点击你的 todo-attachments bucket

2. 点击 Policies 标签

3. 点击 New policy → Use template → 选 Allow access to JPG images in a public folder to anonymous users

4. 在 Allowed operation 下，勾选 SELECT（读取 / 下载）和 INSERT（上传）。下方列表会显示每个操作分别启用哪些客户端函数（upload、download、list 等）。

5. 点击 Save policy。Supabase 会显示一个确认页，列出它将为你勾选的每个操作执行的具体 SQL：

   

6. 在确认页上再点一次 Save policy 确认。回到 Policies 标签页，你会看到 todo-attachments 下多了两条新策略。这样就完成了。只要上传内容符合策略规则，bucket 就会接收上传，并提供文件访问。

小心——这个模板到底允许了什么。 看 SQL 就知道：只允许 .jpg 文件、只允许在名为 public/ 的文件夹里、只允许匿名用户。如果你的上传用的是别的扩展名或路径，策略就不会匹配，上传会悄悄失败。让你的智能体把图片保存为 public/{timestamp}.jpg，让策略能命中（这一步会在下面的上传环节里做）。

安全——这条策略后续也要收紧。 在 authentication 那节课里，你会把它换成一条按用户文件夹（{user_id}/...）限制上传和读取的策略。现在的状态是：任何拿到你应用 URL 的人都能上传。一旦有真实用户，就别再让它这么开放。

加一列来引用文件

你需要在表里有一个地方存放每个上传文件的路径。让你的智能体：

> I need to add a column to my list table in Supabase to store the 
  path to an uploaded image. What SQL should I run to add an 
  "attachment_path" text column that can be null?

智能体已经知道你的表叫什么，所以会给你正确的语句。它大概长这样：

ALTER TABLE public.list_items
  ADD COLUMN attachment_path TEXT;

在 Supabase 控制台里，点击左侧栏的 SQL Editor，粘贴智能体给你的内容，然后点编辑器右上角的 Run。

你应该会在结果区看到 Success. No rows returned。你的表现在已经为每个上传文件的路径预留好位置了。

在应用里上传文件

告诉你的 AI 智能体：

> add an optional file input to my add-item form. accept only JPG 
  images. when the user picks a file, show a small thumbnail or 
  the filename next to the input so they can see the file is 
  attached. the file should upload when they click Add (not when 
  they pick the file), so make sure the Add button is the obvious 
  way to submit both the text and the image together. upload to 
  the todo-attachments Supabase bucket under a path like 
  public/{timestamp}.jpg (the "public/" prefix and ".jpg" extension 
  are required by the storage policy). save the returned path into 
  the attachment_path column for the new item. if no file is 
  picked, just save the item without an attachment.

显示这些文件

> when rendering each list item, if it has an attachment_path, use 
  supabase.storage.from('todo-attachments').getPublicUrl(path) to 
  build a URL. render images inline, and anything else as a download link.

限制用户可以上传什么

storage 是大量安全事故发生的地方。如果不加限制，用户可以上传一个 2GB 的文件、一个恶意可执行文件，或者一个会在其他用户浏览器里执行脚本的 HTML 文件。你需要一些护栏。

> before uploading, enforce these rules:
  - accept only image/jpeg, image/png, image/webp, and application/pdf
  - reject files larger than 5MB
  - rename uploaded files so the stored filename doesn't contain 
    user-supplied text
  - show a friendly error if the check fails

安全——为什么要校验 MIME 类型和文件大小。 浏览器有时会执行那些它认为是 HTML 或 JavaScript 的文件，哪怕它们是当作图片上传上来的。攻击者上传一个名叫 photo.jpg、内容其实是 HTML 的文件，就能在其他用户的浏览器里执行脚本——这就是经典的基于上传的 XSS。在客户端校验 MIME 类型主要是为了 UX，真正的强制要靠 bucket 策略（以及 Supabase 上的文件大小限制）在服务端把关。如果不限制文件大小，一个用户就能撑爆你的配额或者刷爆你的账单。

---

安全要点回顾

进入下一节前，给自己过一遍这份心理清单：

• Key： anon key 放进环境变量；service_role key 永远只待在 Supabase 或一台可信的服务器上。
• 数据库： 生产环境开 RLS，只在你一个人测试时关掉。
• 输入校验： 限制最大长度，去掉首尾空白，渲染回页面前过滤掉 HTML。
• Bucket： 默认 private；只有内容真的公开时才设为 public。
• 上传： MIME 类型和大小限制要在客户端做，同时也要通过 bucket 策略强制执行。
• 永远不要相信客户端。 你在浏览器里强制的所有规则，也要在 Supabase 里再强制一遍。

---

数据库 vs 区块链：什么放在哪里？

你刚刚学会了如何把数据存进数据库、把文件存进云存储。课程后面你会学到如何把数据存到区块链上。它们之间不可互换——每一种都适合不同类型的数据。

这些时候用数据库（和 storage）：

• 数据是私有的或与特定用户相关（用户的资料、待办、上传内容）
• 数据频繁变化（点赞、浏览数、状态更新）
• 你需要进行复杂查询（搜索、筛选、排序）
• 在规模化时关心性能和成本——数据库和 storage 又快又便宜

这些时候用区块链：

• 数据需要公开，并且任何人都可以验证
• 数据必须永久保存且不可篡改
• 不应由任何单一实体拥有或控制
• 你处理的是价值、所有权或信任（代币、合约、投票）

举个实际例子：如果你在做一个市场，用户资料和商品图片大概率会放在 Supabase 里。但商品的所有权、交易历史和支付逻辑，可能会放在区块链上。

大多数真实世界的应用都同时用两者。数据库和 storage 处理那些快速、私有、日常的东西；区块链处理那些需要没有单一所有者、并且永久存在的东西。

---

你刚刚搭出了什么

你的应用现在能：

• 用 Supabase 数据库 记住事情
• 用 Supabase Storage 保存用户上传的文件
• 让 API key 远离 智能体和 Git
• 校验上传内容，把坏文件挡在门外
• 把 RLS 当作防火墙，放在你的数据和互联网之间

这就是一个生产应用的真实骨架。它还缺一大块：它不知道谁在用它。在 sophomore 阶段你会加上 authentication，把 RLS 重新打开，让每个用户的数据真正私有化。

---

接下来是什么

你的应用有了记忆和文件存储。下一步，我们会去看 Monad 的架构，以及区块链如何用一种本质上不同的方式去解决我们刚刚处理过的问题：身份、数据存储和信任。