Pocketbase-GO语言高并发单文件api数据库

阿白 · 发表于 2026-1-4 12:51:49

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要登录才可以下载或查看，没有账号？立即注册微信登陆 QQ登录 sms 手机登录

×

<p><img src="data/attachment/forum/202601/04/124813e3zq9f9bjlfbo83v.webp" alt="QQ20260104-124324.webp" title="QQ20260104-124324.webp" /></p>
<h1>PocketBase 基于 Debian 12 的详细使用指南</h1>
<h2>一、核心需求确认</h2>
<p>你需要一份面向 Debian 12 系统的 PocketBase 完整操作手册，涵盖从环境准备、安装部署到日常运维的全流程，并以 Markdown 格式整理，方便查阅和使用。</p>
<h2>二、PocketBase 详细操作指南</h2>
<h3>1. 什么是 PocketBase</h3>
<p>PocketBase 是一个开源的、轻量级的后端即服务（BaaS），集成了实时数据库、认证系统、文件存储和 REST API，单二进制文件运行，无需额外依赖，非常适合小型项目、原型开发或个人项目。</p>
<h3>2. 环境准备（Debian 12）</h3>
<h4>2.1 系统基础检查与更新</h4>
<p>首先确保 Debian 12 系统为最新状态，执行以下命令：</p>
<pre><code class="language-bash"># 更新软件包索引
sudo apt update -y

# 升级已安装的软件包
sudo apt upgrade -y

# 安装必要的基础工具（curl、unzip、wget）
sudo apt install curl unzip wget -y

# 检查系统架构（PocketBase 需匹配架构下载）
uname -m
# 常见输出：x86_64（amd64）、aarch64（arm64）
</code></pre>
<h4>2.2 防火墙配置（可选但推荐）</h4>
<p>PocketBase 默认使用 8090 端口，需开放该端口：</p>
<pre><code class="language-bash"># 查看防火墙状态
sudo ufw status

# 若未启用，先启用防火墙
sudo ufw enable

# 开放 8090 端口
sudo ufw allow 8090/tcp

# 重载防火墙规则
sudo ufw reload
</code></pre>
<h3>3. PocketBase 安装</h3>
<h4>3.1 下载 PocketBase 二进制文件</h4>
<p>根据系统架构下载对应版本（以最新稳定版为例）：</p>
<pre><code class="language-bash"># 创建 PocketBase 工作目录（推荐）
mkdir -p /opt/pocketbase
cd /opt/pocketbase

# 下载 amd64 架构版本（Debian 12 服务器主流架构）
wget https://github.com/pocketbase/pocketbase/releases/latest/download/pocketbase_linux_amd64.zip

# 若为 arm64 架构，替换为：
# wget https://github.com/pocketbase/pocketbase/releases/latest/download/pocketbase_linux_arm64.zip

# 解压文件
unzip pocketbase_linux_*.zip

# 删除压缩包
rm pocketbase_linux_*.zip

# 添加执行权限
chmod +x pocketbase

# 验证安装（查看版本）
./pocketbase version
</code></pre>
<h4>3.2 测试运行</h4>
<pre><code class="language-bash"># 首次运行 PocketBase
./pocketbase serve

# 运行成功后，终端会输出：
# > Server started at http://0.0.0.0:8090
# > REST API: http://0.0.0.0:8090/api/
# > Admin UI: http://0.0.0.0:8090/_/
</code></pre>
<p>此时可通过 <code>http://你的服务器IP:8090/_/</code> 访问管理后台，首次访问会要求创建管理员账号（用户名/密码）。</p>
<h3>4. PocketBase 基础使用</h3>
<h4>4.1 管理员后台操作</h4>
<ol>
<li>访问 <code>http://服务器IP:8090/_/</code>，输入首次创建的管理员账号登录；</li>
<li><strong>创建数据集合（Collections）</strong>：
<ul>
<li>点击左侧「Collections」→「New collection」；</li>
<li>填写集合名称（如 <code>users</code>）、类型（Base model）；</li>
<li>添加字段（如 <code>username</code>（Text）、<code>email</code>（Email）、<code>age</code>（Number））；</li>
<li>保存后即可通过 API 操作该集合数据。</li>
</ul>
</li>
<li><strong>权限配置</strong>：可针对集合设置「Create/Read/Update/Delete」权限（如开放匿名只读、仅管理员可写等）。</li>
</ol>
<h4>4.2 基础 API 使用</h4>
<p>以 <code>users</code> 集合为例，通过 curl 测试 API：</p>
<pre><code class="language-bash"># 1. 创建一条用户数据（需管理员认证，先获取 token）
# 获取管理员 token
ADMIN_TOKEN=$(curl -X POST http://服务器IP:8090/api/admins/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"你的管理员邮箱","password":"你的管理员密码"}' | jq -r '.token')

# 创建用户
curl -X POST http://服务器IP:8090/api/collections/users/records \
  -H "Content-Type: application/json" \
  -H "Authorization: Admin $ADMIN_TOKEN" \
  -d '{"username":"testuser","email":"test@example.com","age":25}'

# 2. 查询所有用户数据（匿名访问，需先开放 users 集合的 Read 权限）
curl http://服务器IP:8090/api/collections/users/records
</code></pre>
<h3>5. 进阶配置（生产环境必备）</h3>
<h4>5.1 将 PocketBase 配置为系统服务（开机自启）</h4>
<p>创建 systemd 服务文件，确保 PocketBase 后台运行且开机自启：</p>
<pre><code class="language-bash"># 创建服务文件
sudo nano /etc/systemd/system/pocketbase.service
</code></pre>
<p>粘贴以下内容（修改 <code>User</code> 和 <code>WorkingDirectory</code> 为实际路径）：</p>
<pre><code class="language-ini">[Unit]
Description=PocketBase Service
After=network.target

[Service]
Type=simple
User=root  # 推荐使用非 root 用户，如创建 pocketbase 用户
WorkingDirectory=/opt/pocketbase
ExecStart=/opt/pocketbase/pocketbase serve --http=0.0.0.0:8090
Restart=always
RestartSec=5
StandardOutput=journal+console
StandardError=journal+console

[Install]
WantedBy=multi-user.target
</code></pre>
<p>保存后执行以下命令启用服务：</p>
<pre><code class="language-bash"># 重新加载 systemd 配置
sudo systemctl daemon-reload

# 启动 PocketBase 服务
sudo systemctl start pocketbase

# 设置开机自启
sudo systemctl enable pocketbase

# 查看服务状态
sudo systemctl status pocketbase
</code></pre>
<h4>5.2 配置 HTTPS（推荐）</h4>
<p>PocketBase 本身不直接支持 HTTPS，需通过 Nginx 反向代理实现：</p>
<ol>
<li>安装 Nginx：
<pre><code class="language-bash">sudo apt install nginx -y
</code></pre>
</li>
<li>创建 Nginx 配置文件：
<pre><code class="language-bash">sudo nano /etc/nginx/sites-available/pocketbase
</code></pre>
</li>
<li>粘贴以下配置（替换 <code>your-domain.com</code> 为你的域名）：
<pre><code class="language-nginx">server {
listen 80;
server_name your-domain.com;
# 重定向 HTTP 到 HTTPS
return 301 https://$host$request_uri;
}

server {
listen 443 ssl http2;
server_name your-domain.com;

# SSL 证书配置（推荐使用 Let's Encrypt）
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

# 反向代理到 PocketBase
location / {
      proxy_pass http://127.0.0.1:8090;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
}
}
</code></pre>
</li>
<li>启用配置并重启 Nginx：
<pre><code class="language-bash"># 启用配置
sudo ln -s /etc/nginx/sites-available/pocketbase /etc/nginx/sites-enabled/

# 检查配置语法
sudo nginx -t

# 重启 Nginx
sudo systemctl restart nginx
</code></pre>
</li>
<li>申请 Let's Encrypt 免费证书（可选）：
<pre><code class="language-bash"># 安装 certbot
sudo apt install certbot python3-certbot-nginx -y

# 申请证书
sudo certbot --nginx -d your-domain.com
</code></pre>
</li>
</ol>
<h4>5.3 自定义 PocketBase 配置</h4>
<p>PocketBase 的配置文件为 <code>pb_data/pb_config.json</code>（运行后自动生成），可修改以下核心参数：</p>
<ul>
<li><code>appName</code>：应用名称；</li>
<li><code>api.allowedOrigins</code>：跨域允许的域名；</li>
<li><code>mailer</code>：邮件配置（用于密码重置、验证等）；</li>
<li><code>storage</code>：文件存储配置（默认本地，可配置 S3 等）。</li>
</ul>
<p>修改配置后需重启 PocketBase 服务：</p>
<pre><code class="language-bash">sudo systemctl restart pocketbase
</code></pre>
<h3>6. 日常运维</h3>
<h4>6.1 数据备份</h4>
<p>PocketBase 的所有数据（数据库、文件、配置）都在 <code>pb_data</code> 目录，备份该目录即可：</p>
<pre><code class="language-bash"># 创建备份脚本
nano /opt/pocketbase/backup.sh
</code></pre>
<p>粘贴以下内容：</p>
<pre><code class="language-bash">#!/bin/bash
BACKUP_DIR="/opt/pocketbase/backups"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# 停止服务（可选，避免备份时数据写入）
sudo systemctl stop pocketbase

# 压缩 pb_data 目录
zip -r $BACKUP_DIR/pocketbase_backup_$DATE.zip /opt/pocketbase/pb_data

# 启动服务
sudo systemctl start pocketbase

# 删除 7 天前的备份（可选）
find $BACKUP_DIR -name "pocketbase_backup_*.zip" -mtime +7 -delete
</code></pre>
<p>添加执行权限并定时执行：</p>
<pre><code class="language-bash">chmod +x /opt/pocketbase/backup.sh

# 添加到 crontab，每天凌晨 2 点备份
sudo crontab -e
# 粘贴：0 2 * * * /opt/pocketbase/backup.sh
</code></pre>
<h4>6.2 PocketBase 更新</h4>
<pre><code class="language-bash"># 停止服务
sudo systemctl stop pocketbase

# 备份 pb_data（保险）
cp -r /opt/pocketbase/pb_data /opt/pocketbase/pb_data_backup

# 下载最新版本
cd /opt/pocketbase
wget https://github.com/pocketbase/pocketbase/releases/latest/download/pocketbase_linux_amd64.zip
unzip -o pocketbase_linux_amd64.zip  # -o 覆盖原有文件
rm pocketbase_linux_amd64.zip

# 启动服务
sudo systemctl start pocketbase

# 验证版本
/opt/pocketbase/pocketbase version
</code></pre>
<h4>6.3 查看日志</h4>
<pre><code class="language-bash"># 实时查看 PocketBase 日志
sudo journalctl -u pocketbase -f

# 查看最近 100 行日志
sudo journalctl -u pocketbase -n 100
</code></pre>
<h3>7. 常见问题解决</h3>
<ol>
<li><strong>无法访问管理后台</strong>：
<ul>
<li>检查防火墙是否开放 8090 端口（<code>sudo ufw status</code>）；</li>
<li>检查 PocketBase 服务是否运行（<code>sudo systemctl status pocketbase</code>）；</li>
<li>检查服务器安全组（云服务器需开放对应端口）。</li>
</ul>
</li>
<li><strong>API 调用返回 403</strong>：
<ul>
<li>检查集合的权限配置（管理员后台→Collections→对应集合→Rules）；</li>
<li>确认请求头是否携带正确的认证信息（Admin/User Token）。</li>
</ul>
</li>
<li><strong>服务启动失败</strong>：
<ul>
<li>检查 <code>pocketbase.service</code> 文件语法是否正确；</li>
<li>检查 <code>pb_data</code> 目录权限（<code>chmod -R 755 /opt/pocketbase/pb_data</code>）。</li>
</ul>
</li>
</ol>

阿白 · 发表于 2026-1-4 12:54:05

<h1>PocketBase 在堡塔（宝塔）面板下配置进程守护与端口转发</h1>
<h2>一、核心需求确认</h2>
<p>你希望在堡塔（宝塔）面板中为 Debian 12 服务器上的 PocketBase 配置<strong>进程守护</strong>（确保 PocketBase 持续后台运行、崩溃自动重启），并设置<strong>端口转发（反向代理）</strong>，让 PocketBase 可通过 80/443 端口或域名访问（替代默认的 8090 端口）。</p>
<h2>二、前置条件</h2>
<ol>
<li>堡塔面板已成功安装在 Debian 12 服务器（若未安装，可执行官方脚本：<code>curl -sSO https://download.bt.cn/install/install_panel.sh && bash install_panel.sh</code>）；</li>
<li>PocketBase 已按之前的教程安装在服务器（推荐路径：<code>/opt/pocketbase</code>）；</li>
<li>服务器已开放 80/443 端口（堡塔面板默认会开放，可在「安全」模块确认）；</li>
<li>若需域名访问，需提前将域名解析到服务器公网 IP。</li>
</ol>
<h2>三、配置 PocketBase 进程守护（堡塔面板）</h2>
<p>堡塔面板的「进程守护」功能可替代手动配置 systemd 服务，可视化操作更简单，核心是让 PocketBase 后台运行且崩溃自动重启。</p>
<h3>步骤 1：登录堡塔面板</h3>
<p>通过浏览器访问 <code>http://服务器IP:8888</code>（默认端口），输入堡塔面板的账号密码登录。</p>
<h3>步骤 2：进入「进程守护」模块</h3>
<ol>
<li>点击左侧菜单栏的「软件商店」→ 「系统工具」，确认「进程守护」插件已安装（默认已安装，若未安装则点击「安装」）；</li>
<li>安装完成后，点击左侧菜单栏的「进程守护」，进入守护进程管理页面。</li>
</ol>
<h3>步骤 3：添加 PocketBase 守护进程</h3>
<ol>
<li>
<p>点击页面右上角的「添加守护进程」，弹出配置窗口；</p>
</li>
<li>
<p>按以下参数填写（关键项标红）：</p>
<table>
<thead>
<tr>
<th>配置项</th>
<th>填写内容</th>
</tr>
</thead>
<tbody>
<tr>
<td>进程名称</td>
<td>PocketBase（自定义，便于识别）</td>
</tr>
<tr>
<td>运行目录</td>
<td><code>/opt/pocketbase</code>（PocketBase 二进制文件所在目录，需和实际路径一致）</td>
</tr>
<tr>
<td>启动命令</td>
<td><code>./pocketbase serve --http=127.0.0.1:8090</code>（绑定本地回环地址，更安全）</td>
</tr>
<tr>
<td>停止命令</td>
<td><code>pkill pocketbase</code>（可选，用于手动停止进程）</td>
</tr>
<tr>
<td>日志文件</td>
<td><code>/opt/pocketbase/pocketbase.log</code>（自定义日志路径，便于排查问题）</td>
</tr>
<tr>
<td>错误日志文件</td>
<td><code>/opt/pocketbase/pocketbase_error.log</code>（可选，单独记录错误日志）</td>
</tr>
<tr>
<td>自动重启</td>
<td>开启（必选，进程崩溃后自动重启）</td>
</tr>
<tr>
<td>重启间隔</td>
<td>5 秒（默认即可）</td>
</tr>
<tr>
<td>启动用户</td>
<td>root（或你创建的非 root 用户，需确保该用户有 <code>/opt/pocketbase</code> 目录权限）</td>
</tr>
</tbody>
</table>
</li>
<li>
<p>点击「提交」，完成守护进程创建。</p>
</li>
</ol>
<h3>步骤 4：启动并验证守护进程</h3>
<ol>
<li>在「进程守护」列表中找到刚创建的「PocketBase」进程，点击右侧的「启动」；</li>
<li>启动后，进程状态会显示「运行中」，可点击「日志」查看运行日志：
<ul>
<li>若日志中显示 <code>Server started at http://127.0.0.1:8090</code>，说明 PocketBase 已通过守护进程成功运行；</li>
<li>若启动失败，检查「运行目录」「启动命令」是否正确，或查看「错误日志」定位问题（如权限不足可执行 <code>chmod -R 755 /opt/pocketbase</code>）。</li>
</ul>
</li>
</ol>
<h2>四、配置端口转发（反向代理）</h2>
<p>PocketBase 默认监听 8090 端口，直接暴露该端口不够友好，通过堡塔面板的「反向代理」可实现：</p>
<ul>
<li>域名访问（如 <code>https://your-domain.com</code>）→ 转发到 <code>127.0.0.1:8090</code>；</li>
<li>80/443 端口（默认 HTTP/HTTPS 端口）→ 转发到 8090 端口；</li>
<li>同时可一键配置 SSL 证书，实现 HTTPS 访问。</li>
</ul>
<h3>步骤 1：添加站点（域名绑定）</h3>
<ol>
<li>
<p>点击堡塔面板左侧菜单栏的「网站」→「添加站点」；</p>
</li>
<li>
<p>填写站点配置：</p>
<table>
<thead>
<tr>
<th>配置项</th>
<th>填写内容</th>
</tr>
</thead>
<tbody>
<tr>
<td>域名</td>
<td>你的域名（如 <code>pb.example.com</code>，若无需域名可填服务器 IP）</td>
</tr>
<tr>
<td>备注</td>
<td>PocketBase 反向代理（自定义）</td>
</tr>
<tr>
<td>根目录</td>
<td>任意（反向代理无需实际网站文件，如 <code>/www/wwwroot/pocketbase</code>）</td>
</tr>
<tr>
<td>PHP 版本</td>
<td>纯静态（无需 PHP，选择此项）</td>
</tr>
<tr>
<td>数据库</td>
<td>不创建（无需）</td>
</tr>
<tr>
<td>FTP</td>
<td>不创建（无需）</td>
</tr>
</tbody>
</table>
</li>
<li>
<p>点击「提交」，完成站点创建。</p>
</li>
</ol>
<h3>步骤 2：配置反向代理（端口转发）</h3>
<ol>
<li>
<p>在「网站」列表中找到刚创建的站点，点击右侧的「设置」；</p>
</li>
<li>
<p>点击左侧的「反向代理」→「添加反向代理」；</p>
</li>
<li>
<p>填写反向代理配置：</p>
<table>
<thead>
<tr>
<th>配置项</th>
<th>填写内容</th>
</tr>
</thead>
<tbody>
<tr>
<td>代理名称</td>
<td>PocketBase（自定义）</td>
</tr>
<tr>
<td>代理目录</td>
<td>/（根目录，转发所有请求）</td>
</tr>
<tr>
<td>目标URL</td>
<td><code>http://127.0.0.1:8090</code>（PocketBase 运行地址，和守护进程启动命令一致）</td>
</tr>
<tr>
<td>缓存</td>
<td>关闭（避免 API 数据缓存）</td>
</tr>
<tr>
<td>反向代理参数</td>
<td>点击「添加自定义参数」，新增以下参数（解决跨域/Header 传递问题）：<code>proxy_set_header Host $host;``proxy_set_header X-Real-IP $remote_addr;``proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;``proxy_set_header X-Forwarded-Proto $scheme;</code></td>
</tr>
</tbody>
</table>
</li>
<li>
<p>点击「提交」，反向代理配置生效。</p>
</li>
</ol>
<h3>步骤 3：配置 SSL 证书（可选，推荐）</h3>
<p>为了安全访问，建议给域名配置 SSL 证书（堡塔面板支持一键申请 Let's Encrypt 免费证书）：</p>
<ol>
<li>在站点「设置」页面，点击左侧的「SSL」；</li>
<li>选择「Let's Encrypt」→ 勾选需要申请证书的域名 → 点击「申请」；</li>
<li>申请成功后，开启「强制 HTTPS」（自动将 HTTP 请求重定向到 HTTPS）；</li>
<li>点击「保存」，SSL 配置生效。</li>
</ol>
<h3>步骤 4：验证端口转发</h3>
<ol>
<li>访问配置的域名/IP：
<ul>
<li>管理后台：<code>https://你的域名/_/</code>（替代 <code>http://服务器IP:8090/_/</code>）；</li>
<li>API 接口：<code>https://你的域名/api/collections/users/records</code>（替代 8090 端口）；</li>
</ul>
</li>
<li>若能正常访问 PocketBase 管理后台或 API，说明端口转发配置成功。</li>
</ol>
<h2>五、常见问题排查</h2>
<ol>
<li><strong>守护进程启动失败</strong>：
<ul>
<li>检查「运行目录」是否为 PocketBase 二进制文件所在目录；</li>
<li>检查启动命令是否正确（如 <code>./pocketbase</code> 路径是否存在，可在堡塔面板「终端」执行 <code>ls /opt/pocketbase</code> 验证）；</li>
<li>查看「错误日志」，若提示权限不足，执行 <code>chmod +x /opt/pocketbase/pocketbase</code> 赋予执行权限。</li>
</ul>
</li>
<li><strong>反向代理访问 404/502</strong>：
<ul>
<li>502 错误：PocketBase 守护进程未运行，先确认进程状态为「运行中」；</li>
<li>404 错误：反向代理「目标URL」填写错误（需为 <code>127.0.0.1:8090</code>，而非服务器公网 IP）；</li>
<li>跨域错误：检查反向代理「自定义参数」是否添加完整的 Header 配置。</li>
</ul>
</li>
<li><strong>域名无法访问</strong>：
<ul>
<li>确认域名已解析到服务器公网 IP（可通过 <code>ping 你的域名</code> 验证）；</li>
<li>确认服务器安全组/堡塔面板「安全」模块已开放 80/443 端口。</li>
</ul>
</li>
</ol>

digger · 发表于 2026-1-4 12:57:08

<h1>PocketBase 保留目录说明 & 钩子（Hook）调用方式与示例</h1>
<h2>一、核心需求确认</h2>
<p>你希望了解 PocketBase 运行过程中自动生成/识别的<strong>保留目录</strong>的名称和具体作用，同时掌握 PocketBase 钩子（Hook）的调用方式，并通过实际示例理解钩子在业务场景中的应用（如数据校验、事件触发、自定义逻辑等）。</p>
<h2>二、PocketBase 保留目录详解</h2>
<p>PocketBase 运行时会在其工作目录（如 <code>/opt/pocketbase</code>）自动生成/识别多个保留目录（文件名固定，PocketBase 会优先读取），所有核心数据、配置、自定义逻辑都集中在这些目录中。以下是所有保留目录的名称、作用及关键细节：</p>
<table>
<thead>
<tr>
<th>目录名称</th>
<th>核心作用</th>
<th>关键文件/子目录</th>
<th>适用场景</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>pb_data/</code></td>
<td><strong>最核心目录</strong>，存储所有持久化数据（数据库、配置、文件、日志等）</td>
<td>- <code>pb.db</code>：SQLite 核心数据库（存储集合、记录、用户等）- <code>pb_config.json</code>：全局配置文件（应用名称、跨域、邮件等）- <code>storage/</code>：文件存储目录（上传的图片/文件）- <code>logs/</code>：运行日志（可选）- <code>pb_auth.json</code>：认证相关配置</td>
<td>数据备份、配置修改、文件存储管理</td>
</tr>
<tr>
<td><code>pb_hooks/</code></td>
<td>存放 JS/TS 钩子脚本，PocketBase 启动时自动加载，用于扩展业务逻辑</td>
<td><code>*.js</code>/<code>*.ts</code>（如 <code>users.hooks.js</code>）</td>
<td>数据校验、事件触发、自定义认证、请求拦截</td>
</tr>
<tr>
<td><code>pb_migrations/</code></td>
<td>数据库迁移脚本目录，用于管理集合结构变更（版本升级/手动修改表结构）</td>
<td><code>*.js</code>/<code>*.ts</code>（如 <code>20240104120000_init.js</code>）</td>
<td>生产环境集合结构变更、版本迭代</td>
</tr>
<tr>
<td><code>pb_public/</code></td>
<td>静态文件托管目录，可通过 URL 直接访问（无需认证）</td>
<td>任意静态文件（如 <code>index.html</code>、<code>logo.png</code>）</td>
<td>托管前端静态页面、公共资源（如图片、JS）</td>
</tr>
</tbody>
</table>
<h3>各目录详细说明</h3>
<h4>1. <code>pb_data/</code>（核心数据目录）</h4>
<ul>
<li><strong>不可删除</strong>：删除该目录会丢失所有数据（数据库、配置、上传文件）；</li>
<li><strong>备份优先级</strong>：日常运维只需备份该目录即可完整恢复 PocketBase 所有数据；</li>
<li><strong>关键文件说明</strong>：
<ul>
<li><code>pb.db</code>：SQLite 数据库文件，存储集合定义、记录数据、管理员/用户账号等核心数据；</li>
<li><code>pb_config.json</code>：自动生成的配置文件，可手动修改（如跨域允许的域名、邮件服务器配置），修改后需重启 PocketBase；</li>
<li><code>storage/</code>：默认存储用户上传的文件（如集合中「File」类型字段的文件），路径对应 API 返回的 <code>fileUrl</code>；</li>
<li>权限要求：运行 PocketBase 的用户需有该目录的读写权限（如 <code>chmod -R 755 pb_data/</code>）。</li>
</ul>
</li>
</ul>
<h4>2. <code>pb_hooks/</code>（钩子脚本目录）</h4>
<ul>
<li><strong>自动加载</strong>：PocketBase 启动时会扫描该目录下所有 <code>.js</code>/<code>.ts</code> 文件并执行，无需手动配置；</li>
<li><strong>运行环境</strong>：基于 Go 内置的 ESModule 运行时，支持大部分 ES6+ 语法，可直接使用 <code>console.log</code> 调试；</li>
<li><strong>无依赖</strong>：暂不支持 npm 包，需用原生 JS/TS 编写逻辑。</li>
</ul>
<h4>3. <code>pb_migrations/</code>（数据库迁移目录）</h4>
<ul>
<li><strong>自动生成</strong>：在管理后台修改集合结构（如添加字段）时，会自动生成迁移脚本；</li>
<li><strong>手动执行</strong>：可通过命令 <code>./pocketbase migrate up</code> 执行未应用的迁移脚本；</li>
<li><strong>回滚</strong>：支持 <code>./pocketbase migrate down</code> 回滚最近一次迁移（需脚本支持）。</li>
</ul>
<h4>4. <code>pb_public/</code>（静态文件目录）</h4>
<ul>
<li><strong>访问方式</strong>：文件路径对应 URL 路径，如 <code>pb_public/logo.png</code> 可通过 <code>http://域名/public/logo.png</code> 访问；</li>
<li><strong>权限</strong>：所有文件无需认证即可访问，适合存放公共静态资源（不建议存放敏感文件）。</li>
</ul>
<h2>三、PocketBase 钩子（Hook）调用方式与示例</h2>
<h3>1. 钩子核心概念</h3>
<p>PocketBase 钩子是<strong>服务端事件驱动脚本</strong>，可拦截/处理系统核心事件（如数据创建/更新、用户认证、服务启动等），实现自定义业务逻辑（如数据校验、自动填充字段、日志记录、权限控制）。</p>
<p>钩子分为两类：</p>
<ul>
<li><strong>集合钩子（Collection Hooks）</strong>：针对特定集合的操作（如 <code>users</code> 集合的创建/更新），最常用；</li>
<li><strong>全局钩子（App Hooks）</strong>：针对全局事件（如服务启动、HTTP 请求拦截、用户登录）。</li>
</ul>
<h3>2. 钩子基本使用步骤</h3>
<ol>
<li>在 PocketBase 工作目录（如 <code>/opt/pocketbase</code>）创建 <code>pb_hooks</code> 目录：
<pre><code class="language-bash">mkdir -p /opt/pocketbase/pb_hooks
</code></pre>
</li>
<li>在 <code>pb_hooks</code> 目录下创建 <code>.js</code> 文件（如 <code>users.hooks.js</code>）；</li>
<li>编写钩子逻辑，保存后重启 PocketBase 守护进程（堡塔面板「进程守护」→ 重启）；</li>
<li>测试触发条件（如创建一条用户记录），验证钩子是否生效。</li>
</ol>
<h3>3. 常用钩子示例</h3>
<h4>示例 1：集合钩子 - 数据创建前校验（必填字段+格式校验）</h4>
<p>场景：<code>users</code> 集合创建记录时，强制校验「email」字段格式，且「username」字段不能为空。</p>
<p>创建 <code>pb_hooks/users.hooks.js</code>：</p>
<pre><code class="language-javascript">// 监听 users 集合的 beforeCreate 事件（创建记录前触发）
onRecordBeforeCreate((e) => {
  // 仅针对 users 集合生效
  if (e.record.collectionName !== "users") {
return;
  }

  // 1. 校验 username 不能为空
  const username = e.record.get("username");
  if (!username || username.trim() === "") {
throw new Error("用户名不能为空！"); // 抛出错误会终止创建操作，前端会收到该错误信息
  }

  // 2. 校验 email 格式
  const email = e.record.get("email");
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
throw new Error("邮箱格式不正确！");
  }

  // 3. 自动填充创建时间（无需前端传参）
  e.record.set("created_at", new Date().toISOString());
});
</code></pre>
<p><strong>触发方式</strong>：调用 <code>users</code> 集合的创建 API 时自动触发：</p>
<pre><code class="language-bash"># 测试：传入错误邮箱，会返回「邮箱格式不正确」
curl -X POST http://域名/api/collections/users/records \
  -H "Content-Type: application/json" \
  -d '{"username":"test","email":"invalid-email","age":25}'
</code></pre>
<h4>示例 2：集合钩子 - 数据更新后记录日志</h4>
<p>场景：<code>users</code> 集合记录更新后，自动将操作日志写入 <code>user_logs</code> 集合（需先创建该集合，包含 <code>user_id</code>、<code>operation</code>、<code>update_time</code> 字段）。</p>
<p>创建 <code>pb_hooks/users.hooks.js</code>：</p>
<pre><code class="language-javascript">// 监听 users 集合的 afterUpdate 事件（更新记录后触发）
onRecordAfterUpdate(async (e) => {
  if (e.record.collectionName !== "users") {
return;
  }

  // 获取更新的用户ID和操作时间
  const userId = e.record.id;
  const updateTime = new Date().toISOString();

  // 写入日志到 user_logs 集合
  await $app.dao().createRecord(
$app.dao().findCollectionByNameOrId("user_logs"),
{
   user_id: userId,
   operation: "用户信息更新",
   update_time: updateTime,
}
  );

  console.log(`用户 ${userId} 信息已更新，日志已记录`); // 日志会输出到 PocketBase 运行日志
});
</code></pre>
<h4>示例 3：全局钩子 - 服务启动时初始化</h4>
<p>场景：PocketBase 启动时，自动检查 <code>settings</code> 集合是否存在默认配置，不存在则创建。</p>
<p>创建 <code>pb_hooks/app.hooks.js</code>：</p>
<pre><code class="language-javascript">// 监听服务启动后事件
onAppAfterServe((e) => {
  console.log("PocketBase 服务已启动，开始初始化默认配置");

  // 获取 settings 集合
  const settingsCollection = $app.dao().findCollectionByNameOrId("settings");
  if (!settingsCollection) {
console.log("settings 集合不存在，跳过初始化");
return;
  }

  // 检查是否已有默认配置
  const defaultSettings = $app.dao().findFirstRecordByFilter(
"settings",
"key = 'site_name'",
""
  );

  // 无默认配置则创建
  if (!defaultSettings) {
const record = new Record(settingsCollection);
record.set("key", "site_name");
record.set("value", "我的 PocketBase 应用");
$app.dao().saveRecord(record);
console.log("默认站点名称已创建");
  }
});
</code></pre>
<h4>示例 4：全局钩子 - 拦截 HTTP 请求添加跨域头</h4>
<p>场景：自定义跨域配置（替代 <code>pb_config.json</code> 中的跨域设置），允许指定域名的跨域请求。</p>
<p>创建 <code>pb_hooks/app.hooks.js</code>：</p>
<pre><code class="language-javascript">// 监听所有 HTTP 请求
onHttpRequest((e) => {
  // 获取请求的 Origin 头
  const origin = e.request.headers.get("Origin");
  // 允许的跨域域名列表
  const allowedOrigins = ["https://your-domain.com", "http://localhost:3000"];

  // 若 Origin 在允许列表中，添加跨域头
  if (allowedOrigins.includes(origin)) {
e.response.headers.set("Access-Control-Allow-Origin", origin);
e.response.headers.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
e.response.headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
  }

  // 处理 OPTIONS 预检请求
  if (e.request.method === "OPTIONS") {
e.response.status = 204;
e.response.body = "";
  }
});
</code></pre>
<h4>示例 5：认证钩子 - 自定义用户登录逻辑</h4>
<p>场景：用户登录时，额外校验「账号是否禁用」（<code>users</code> 集合需添加 <code>is_disabled</code> 布尔字段）。</p>
<p>创建 <code>pb_hooks/auth.hooks.js</code>：</p>
<pre><code class="language-javascript">// 监听用户密码登录事件
onRecordAuthWithPassword((e) => {
  // 仅针对 users 集合的登录
  if (e.record.collectionName !== "users") {
return;
  }

  // 检查用户是否被禁用
  const isDisabled = e.record.get("is_disabled");
  if (isDisabled) {
throw new Error("该账号已被禁用，请联系管理员！"); // 终止登录
  }

  // 登录成功后，记录最后登录时间
  e.record.set("last_login_at", new Date().toISOString());
  await $app.dao().saveRecord(e.record);

  console.log(`用户 ${e.record.id} 登录成功，最后登录时间已更新`);
});
</code></pre>
<h3>4. 钩子调试技巧</h3>
<ul>
<li><strong>日志输出</strong>：使用 <code>console.log(xxx)</code> 输出调试信息，日志会写入 PocketBase 运行日志（堡塔面板「进程守护」→「日志」可查看）；</li>
<li><strong>错误排查</strong>：钩子脚本语法错误会导致 PocketBase 启动失败，可在终端手动运行 <code>./pocketbase serve</code> 查看具体错误信息；</li>
<li><strong>参数打印</strong>：触发钩子时，打印事件对象 <code>e</code> 查看可用参数（如 <code>console.log(JSON.stringify(e.record))</code>）。</li>
</ul>
<h2>四、总结</h2>
<ol>
<li><strong>保留目录核心要点</strong>：
<ul>
<li><code>pb_data/</code> 是核心数据仓，备份该目录即可恢复所有数据；</li>
<li><code>pb_hooks/</code> 存放自定义钩子脚本，启动时自动加载；</li>
<li><code>pb_public/</code> 托管无需认证的静态文件，<code>pb_migrations/</code> 管理数据库结构变更。</li>
</ul>
</li>
<li><strong>钩子使用核心要点</strong>：
<ul>
<li>钩子分「集合钩子」（针对数据操作）和「全局钩子」（针对系统事件），放在 <code>pb_hooks/</code> 目录自动加载；</li>
<li>常用钩子：<code>onRecordBeforeCreate</code>（数据校验）、<code>onRecordAfterUpdate</code>（日志记录）、<code>onHttpRequest</code>（跨域配置）；</li>
<li>钩子中抛出错误会终止原操作，适合做数据校验；可通过 <code>$app.dao()</code> 操作数据库（如创建/更新记录）。</li>
</ul>
</li>
<li><strong>实战建议</strong>：
<ul>
<li>钩子脚本优先实现核心业务逻辑（校验、自动填充），避免复杂计算；</li>
<li>修改钩子后需重启 PocketBase 才能生效；</li>
<li>生产环境需备份 <code>pb_hooks/</code> 目录，避免钩子脚本丢失。</li>
</ul>
</li>
</ol>

打工日常 · 发表于 2026-1-4 13:00:20

<h1>Debian 12 下 PocketBase 全维度配置指南</h1>
<h2>一、核心需求确认</h2>
<p>你需要在 Debian 12 系统中完成 PocketBase 的<strong>全场景配置</strong>，包括基础网络（端口、绑定地址）、邮件（SMTP）、存储（本地/S3）、安全（跨域、认证）、应用基础（日志、时区）等核心配置，同时掌握配置的生效方式、备份与问题排查方法，适配生产环境的实际需求。</p>
<h2>二、PocketBase 配置的核心入口（Debian 12 环境）</h2>
<p>PocketBase 的配置主要通过 4 种方式实现（优先级：命令行参数 > 管理后台 > 配置文件 > 钩子脚本），所有配置最终会落地到 <code>pb_data/pb_config.json</code>（运行后自动生成），以下是各入口的适用场景：</p>
<table>
<thead>
<tr>
<th>配置方式</th>
<th>操作路径</th>
<th>适用场景</th>
</tr>
</thead>
<tbody>
<tr>
<td>配置文件</td>
<td><code>/opt/pocketbase/pb_data/pb_config.json</code>（手动编辑）</td>
<td>所有基础配置（网络、邮件、存储、安全）</td>
</tr>
<tr>
<td>命令行启动参数</td>
<td>启动时追加参数（如 <code>./pocketbase serve --http=0.0.0.0:8080</code>）</td>
<td>临时覆盖配置（如测试端口、调试模式）</td>
</tr>
<tr>
<td>管理后台</td>
<td><code>http://域名/_/</code> → 设置（Settings）</td>
<td>可视化配置（邮件、跨域、认证策略）</td>
</tr>
<tr>
<td>钩子脚本</td>
<td><code>pb_hooks/</code> 下的 JS 脚本</td>
<td>自定义配置（如动态跨域、自定义认证规则）</td>
</tr>
</tbody>
</table>
<h3>前置操作（Debian 12）</h3>
<ol>
<li>确认 PocketBase 工作目录（默认 <code>/opt/pocketbase</code>），若路径不同需替换下文所有路径；</li>
<li>确保对 <code>pb_data/</code> 目录有读写权限：
<pre><code class="language-bash">sudo chmod -R 755 /opt/pocketbase/pb_data
sudo chown -R root:root /opt/pocketbase/pb_data  # 或你的运行用户
</code></pre>
</li>
</ol>
<h2>三、核心配置模块（Debian 12 实操）</h2>
<h3>1. 基础网络配置（端口、绑定地址、HTTPS）</h3>
<h4>1.1 修改默认端口/绑定地址（3种方式）</h4>
<p>PocketBase 默认监听 <code>0.0.0.0:8090</code>，以下是修改方式：</p>
<h5>方式1：命令行参数（临时生效，重启后失效）</h5>
<pre><code class="language-bash"># 切换到 PocketBase 目录
cd /opt/pocketbase

# 监听 8080 端口，仅绑定本地回环地址（仅服务器内部访问）
./pocketbase serve --http=127.0.0.1:8080

# 监听 80 端口（需 root 权限），绑定所有网卡
sudo ./pocketbase serve --http=0.0.0.0:80
</code></pre>
<h5>方式2：配置文件（永久生效）</h5>
<ol>
<li>编辑配置文件：
<pre><code class="language-bash">nano /opt/pocketbase/pb_data/pb_config.json
</code></pre>
</li>
<li>添加/修改 <code>api</code> 节点（无则新增）：
<pre><code class="language-json">{
  "api": {
"httpAddr": "0.0.0.0:8080",  // 绑定地址+端口
"httpTimeout": 30          // 请求超时时间（秒）
  }
}
</code></pre>
</li>
<li>保存后重启 PocketBase：
<pre><code class="language-bash"># systemd 服务方式
sudo systemctl restart pocketbase

# 堡塔面板方式：进程守护 → 重启 PocketBase
</code></pre>
</li>
</ol>
<h5>方式3：堡塔面板进程守护（永久生效）</h5>
<ol>
<li>登录堡塔面板 → 进程守护 → 找到 PocketBase 进程 → 编辑；</li>
<li>修改「启动命令」为：
<pre><code class="language-bash">./pocketbase serve --http=0.0.0.0:8080
</code></pre>
</li>
<li>保存并重启进程。</li>
</ol>
<h4>1.2 配置 HTTPS（Debian 12 推荐 Nginx 反向代理）</h4>
<p>PocketBase 自身不直接支持 HTTPS，Debian 12 下推荐通过 Nginx 配置（替代 PocketBase 内置的 HTTPS 方式，更稳定）：</p>
<ol>
<li>安装 Nginx（Debian 12）：
<pre><code class="language-bash">sudo apt install nginx -y
</code></pre>
</li>
<li>创建 Nginx 配置文件：
<pre><code class="language-bash">sudo nano /etc/nginx/sites-available/pocketbase-https
</code></pre>
</li>
<li>粘贴以下配置（替换 <code>your-domain.com</code> 为你的域名）：
<pre><code class="language-nginx">server {
listen 80;
server_name your-domain.com;
# 重定向 HTTP 到 HTTPS
return 301 https://$host$request_uri;
}

server {
listen 443 ssl http2;
server_name your-domain.com;

# SSL 证书（Let's Encrypt 免费证书）
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;

# 反向代理到 PocketBase
location / {
      proxy_pass http://127.0.0.1:8090;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
}
}
</code></pre>
</li>
<li>启用配置并重启 Nginx：
<pre><code class="language-bash">sudo ln -s /etc/nginx/sites-available/pocketbase-https /etc/nginx/sites-enabled/
sudo nginx -t  # 校验配置语法
sudo systemctl restart nginx
</code></pre>
</li>
<li>申请 Let's Encrypt 证书（Debian 12）：
<pre><code class="language-bash">sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d your-domain.com
</code></pre>
</li>
</ol>
<h3>2. 邮件配置（SMTP，用于密码重置/验证）</h3>
<p>PocketBase 需配置 SMTP 才能发送邮件（如用户注册验证、密码重置），以下是 Debian 12 下的配置步骤：</p>
<h4>方式1：管理后台可视化配置（推荐）</h4>
<ol>
<li>
<p>访问 <code>http://域名/_/</code> → 左侧「Settings」→「Mailer」；</p>
</li>
<li>
<p>填写 SMTP 信息（以腾讯企业邮/QQ 邮箱为例）：</p>
<table>
<thead>
<tr>
<th>配置项</th>
<th>填写内容（QQ 邮箱）</th>
</tr>
</thead>
<tbody>
<tr>
<td>From address</td>
<td>你的邮箱（如 <code>xxx@qq.com</code>）</td>
</tr>
<tr>
<td>From name</td>
<td>PocketBase 应用（自定义）</td>
</tr>
<tr>
<td>SMTP host</td>
<td>smtp.qq.com</td>
</tr>
<tr>
<td>SMTP port</td>
<td>465（SSL）/587（TLS）</td>
</tr>
<tr>
<td>SMTP username</td>
<td>你的邮箱（如 <code>xxx@qq.com</code>）</td>
</tr>
<tr>
<td>SMTP password</td>
<td>邮箱授权码（非登录密码）</td>
</tr>
<tr>
<td>SMTP secure</td>
<td>SSL（对应 465 端口）/TLS（对应 587 端口）</td>
</tr>
</tbody>
</table>
</li>
<li>
<p>点击「Test」测试邮件发送，成功后点击「Save」保存。</p>
</li>
</ol>
<h4>方式2：手动编辑配置文件（永久生效）</h4>
<ol>
<li>编辑 <code>pb_config.json</code>：
<pre><code class="language-bash">nano /opt/pocketbase/pb_data/pb_config.json
</code></pre>
</li>
<li>添加/修改 <code>mailer</code> 节点：
<pre><code class="language-json">{
  "mailer": {
"fromAddress": "xxx@qq.com",
"fromName": "PocketBase 应用",
"smtp": {
   "host": "smtp.qq.com",
   "port": 465,
   "username": "xxx@qq.com",
   "password": "你的邮箱授权码",
   "secure": true  // true=SSL，false=TLS
}
  }
}
</code></pre>
</li>
<li>重启 PocketBase 生效。</li>
</ol>
<h3>3. 存储配置（本地/S3 兼容存储）</h3>
<p>PocketBase 默认将上传文件存储在 <code>pb_data/storage/</code>，可配置为 S3 兼容存储（如阿里云 OSS、腾讯云 COS）。</p>
<h4>3.1 本地存储配置（默认，调整路径）</h4>
<ol>
<li>编辑 <code>pb_config.json</code>：
<pre><code class="language-bash">nano /opt/pocketbase/pb_data/pb_config.json
</code></pre>
</li>
<li>修改 <code>storage</code> 节点（自定义本地存储路径）：
<pre><code class="language-json">{
  "storage": {
"local": {
   "path": "/data/pocketbase/storage"  // 自定义存储路径（Debian 12 需提前创建）
},
"active": "local"  // 启用本地存储
  }
}
</code></pre>
</li>
<li>创建自定义路径并授权：
<pre><code class="language-bash">sudo mkdir -p /data/pocketbase/storage
sudo chmod -R 755 /data/pocketbase/storage
sudo chown -R root:root /data/pocketbase/storage
</code></pre>
</li>
<li>重启 PocketBase 生效。</li>
</ol>
<h4>3.2 S3 兼容存储配置（阿里云 OSS 示例）</h4>
<ol>
<li>编辑 <code>pb_config.json</code>：
<pre><code class="language-json">{
  "storage": {
"s3": {
   "accessKeyID": "你的阿里云 AccessKey ID",
   "secretAccessKey": "你的阿里云 AccessKey Secret",
   "region": "oss-cn-beijing",  // 阿里云 OSS 地域
   "bucket": "your-bucket-name",  // OSS 桶名称
   "endpoint": "oss-cn-beijing.aliyuncs.com",  // OSS 端点
   "disableSSL": false,
   "forcePathStyle": false
},
"active": "s3"  // 启用 S3 存储
  }
}
</code></pre>
</li>
<li>重启 PocketBase 生效，上传文件会自动存储到 OSS 桶。</li>
</ol>
<h3>4. 安全配置（跨域、认证、密码策略）</h3>
<h4>4.1 跨域配置（CORS）</h4>
<h5>方式1：管理后台配置</h5>
<ol>
<li>访问 <code>http://域名/_/</code> →「Settings」→「API」；</li>
<li>在「Allowed origins」中填写允许的跨域域名（如 <code>https://your-domain.com,http://localhost:3000</code>），多个域名用逗号分隔；</li>
<li>可选：开启「Allow credentials」（允许携带 Cookie/Token）；</li>
<li>保存后立即生效（无需重启）。</li>
</ol>
<h5>方式2：配置文件配置</h5>
<ol>
<li>编辑 <code>pb_config.json</code>：
<pre><code class="language-json">{
  "api": {
"allowedOrigins": ["https://your-domain.com", "http://localhost:3000"],
"allowCredentials": true
  }
}
</code></pre>
</li>
<li>重启 PocketBase 生效。</li>
</ol>
<h4>4.2 认证安全配置（Token 超时、密码策略）</h4>
<ol>
<li>
<p>管理后台配置路径：<code>Settings</code> →「Auth」；</p>
</li>
<li>
<p>核心配置项：</p>
<table>
<thead>
<tr>
<th>配置项</th>
<th>作用</th>
</tr>
</thead>
<tbody>
<tr>
<td>Token duration</td>
<td>用户 Token 有效期（如 7d=7 天，1h=1 小时）</td>
</tr>
<tr>
<td>Password min length</td>
<td>用户密码最小长度（推荐 ≥8）</td>
</tr>
<tr>
<td>Password require chars</td>
<td>密码复杂度（是否要求大小写、数字、特殊字符）</td>
</tr>
<tr>
<td>Max failed attempts</td>
<td>登录失败最大次数（超过后锁定账号）</td>
</tr>
</tbody>
</table>
</li>
<li>
<p>保存后立即生效。</p>
</li>
</ol>
<h4>4.3 管理后台安全配置</h4>
<ol>
<li>限制管理后台访问 IP（Debian 12 防火墙）：
<pre><code class="language-bash"># 仅允许 192.168.1.100 访问 8090 端口（管理后台）
sudo ufw allow from 192.168.1.100 to any port 8090
sudo ufw reload
</code></pre>
</li>
<li>或通过钩子拦截（推荐，见前文请求拦截示例）。</li>
</ol>
<h3>5. 应用基础配置（名称、日志、时区）</h3>
<h4>5.1 应用名称/描述配置</h4>
<ol>
<li>编辑 <code>pb_config.json</code>：
<pre><code class="language-json">{
  "app": {
"name": "我的 PocketBase 应用",
"url": "https://your-domain.com",
"description": "基于 PocketBase 的后端服务"
  }
}
</code></pre>
</li>
<li>重启生效。</li>
</ol>
<h4>5.2 日志配置（Debian 12 持久化日志）</h4>
<ol>
<li>编辑 <code>pb_config.json</code>：
<pre><code class="language-json">{
  "logs": {
"level": "info",  // 日志级别：debug/info/warn/error
"file": "/var/log/pocketbase/pb.log"  // 日志文件路径（Debian 12）
  }
}
</code></pre>
</li>
<li>创建日志目录并授权：
<pre><code class="language-bash">sudo mkdir -p /var/log/pocketbase
sudo chmod -R 755 /var/log/pocketbase
sudo chown -R root:root /var/log/pocketbase
</code></pre>
</li>
<li>重启 PocketBase 生效，日志会自动写入 <code>/var/log/pocketbase/pb.log</code>。</li>
</ol>
<h4>5.3 时区配置（Debian 12 系统时区同步）</h4>
<ol>
<li>先设置 Debian 12 系统时区：
<pre><code class="language-bash">sudo timedatectl set-timezone Asia/Shanghai
</code></pre>
</li>
<li>PocketBase 会自动同步系统时区，无需额外配置；若需手动指定，可通过启动参数：
<pre><code class="language-bash">./pocketbase serve --timezone=Asia/Shanghai
</code></pre>
</li>
</ol>
<h3>6. 自定义配置（钩子脚本补充）</h3>
<p>对于配置文件无法实现的自定义需求，通过 <code>pb_hooks/</code> 脚本补充：</p>
<h4>示例：动态跨域配置（根据请求域名放行）</h4>
<pre><code class="language-javascript">// pb_hooks/cors.hooks.js
onHttpRequest((e) => {
  // 动态允许所有子域名跨域
  const origin = e.request.headers.get("Origin");
  if (origin && origin.endsWith(".your-domain.com")) {
e.response.headers.set("Access-Control-Allow-Origin", origin);
e.response.headers.set("Access-Control-Allow-Credentials", "true");
  }
  e.next();
});
</code></pre>
<h2>四、配置的备份、恢复与生效方式</h2>
<h3>1. 配置生效方式</h3>
<table>
<thead>
<tr>
<th>配置类型</th>
<th>生效方式</th>
</tr>
</thead>
<tbody>
<tr>
<td>命令行参数</td>
<td>启动时立即生效（临时）</td>
</tr>
<tr>
<td>管理后台配置</td>
<td>保存后立即生效（部分需重启，如邮件）</td>
</tr>
<tr>
<td>配置文件修改</td>
<td>重启 PocketBase 生效</td>
</tr>
<tr>
<td>钩子脚本</td>
<td>重启 PocketBase 生效</td>
</tr>
</tbody>
</table>
<h3>2. 配置备份（Debian 12）</h3>
<pre><code class="language-bash"># 备份 pb_config.json（核心配置文件）
cp /opt/pocketbase/pb_data/pb_config.json /opt/pocketbase/pb_config.backup.json

# 完整备份所有配置+数据（推荐）
zip -r /opt/pocketbase_backup_$(date +%Y%m%d).zip /opt/pocketbase/pb_data/
</code></pre>
<h3>3. 配置恢复</h3>
<pre><code class="language-bash"># 恢复配置文件
cp /opt/pocketbase/pb_config.backup.json /opt/pocketbase/pb_data/pb_config.json

# 重启 PocketBase
sudo systemctl restart pocketbase
</code></pre>
<h3>4. 常见配置问题排查</h3>
<h4>问题1：配置修改后不生效</h4>
<ul>
<li>检查是否重启 PocketBase；</li>
<li>检查配置文件语法（JSON 格式是否正确，可通过 <code>https://jsonlint.com/</code> 校验）；</li>
<li>检查配置文件权限（是否可读写）。</li>
</ul>
<h4>问题2：邮件发送失败</h4>
<ul>
<li>检查 SMTP 端口是否开放（Debian 12 防火墙/云服务器安全组）；</li>
<li>验证 SMTP 账号/授权码是否正确；</li>
<li>查看 PocketBase 日志：<code>sudo journalctl -u pocketbase -f</code>。</li>
</ul>
<h4>问题3：端口无法访问</h4>
<ul>
<li>检查 Debian 12 防火墙：<code>sudo ufw status</code>；</li>
<li>检查云服务器安全组是否开放端口；</li>
<li>检查 PocketBase 绑定地址（是否为 <code>0.0.0.0</code>，而非 <code>127.0.0.1</code>）。</li>
</ul>
<h2>五、总结</h2>
<ol>
<li><strong>配置核心入口</strong>：
<ul>
<li>基础配置（网络、邮件、存储）优先通过 <code>pb_config.json</code> 或管理后台配置（永久生效）；</li>
<li>临时测试用命令行参数（重启失效）；</li>
<li>自定义逻辑用钩子脚本补充。</li>
</ul>
</li>
<li><strong>Debian 12 关键操作</strong>：
<ul>
<li>修改配置文件后需重启 PocketBase（systemctl/堡塔面板）；</li>
<li>自定义路径（存储/日志）需提前创建并授权；</li>
<li>HTTPS 推荐用 Nginx 反向代理，而非 PocketBase 内置方式。</li>
</ul>
</li>
<li><strong>生产环境必配</strong>：
<ul>
<li>邮件配置（密码重置）、HTTPS（安全访问）、跨域配置（前端访问）、日志持久化（排查问题）；</li>
<li>配置文件定期备份，避免丢失。</li>
</ul>
</li>
</ol>
<p>通过以上配置，可完全适配 Debian 12 系统下 PocketBase 的生产环境需求，兼顾安全性、稳定性和自定义性。</p>

[源码] Pocketbase-GO语言高并发单文件api数据库

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

温馨提示：

电梯直达
评论3

回复

浏览过的版块

[源码] Pocketbase-GO语言高并发单文件api数据库

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

温馨提示：

电梯直达 评论3

回复

浏览过的版块

电梯直达
评论3