全栈一定得是大人开发吗？来看看16岁PHP全栈的项目

ZuzShortURL 是一个专为创业团队、电商平台及中小型企业设计的开源短链接SaaS解决方案。它基于 PHP 和 PostgreSQL 构建，提供高效、安全的短链接生成、管理和分析功能，支持自定义域名、二维码生成以及多用户管理。该项目强调简易部署和可扩展性，适用于从个人测试到生产环境的各种场景。

项目亮点包括：

• 双端支持：前端响应式设计，适配桌面和移动设备。
• 安全机制：通过环境变量存储敏感信息，确保配置安全。
• 开源协议：采用 MIT 许可，允许自由使用、修改和商用。

您可以访问在线Demo体验功能（后台地址：zuz.asia/admin，Token… 数据会定期清空，仅供测试使用。生产环境请参考本教程部署。

项目仓库：GitHub - JanePHPDev/ZuzShortURL
官网：ZeinkLab
QQ 群：491102600（欢迎加入讨论）

重要提示：本教程聚焦部署过程的细化说明。首次部署后，请务必执行数据库迁移（详见后文）。当前版本为 v1.1.9，支持直接更新。

部署概述

ZuzShortURL 支持多种部署方式，包括 Docker 容器化部署、传统 Apache + PostgreSQL 部署，以及 Vercel 无服务器部署。选择方案取决于您的环境：Docker 适合容器化爱好者，Apache 适合 VPS 用户，Vercel 适合快速上线。

无论哪种方式，都需准备：

• PostgreSQL 数据库：推荐使用 Supabase 免费方案（详见后文）。
• 环境变量：DATABASE_URL（数据库连接串）和 ADMIN_TOKEN（管理员令牌）。
• 域名（可选）：自定义短链接域名。

部署后，首次访问需运行数据库迁移初始化表结构。以下章节将逐一细化每个方案的步骤，包括前提检查、潜在问题排查和最佳实践。

Docker 部署方案

Docker 方案利用预构建镜像（基于 Apache + PHP 8.3），简化环境配置。镜像已集成 pdo_pgsql 扩展、Rewrite 和 Env 模块，支持伪静态路由。默认暴露 8437 端口（可自定义）。当前不支持 Docker Compose，请使用 docker run 命令手动部署。

前提条件

1. 安装 Docker：从官方下载页面获取并安装 Docker Desktop（适用于 Windows/macOS）或 Docker Engine（Linux）。验证安装：运行 docker --version，确保版本 ≥ 20.10。
2. 准备数据库：设置 PostgreSQL 实例。推荐 Supabase（免费 500 MB 存储，每日 500 万 API 调用）。如果使用本地数据库，确保其可从容器访问（详见提示）。
3. 环境变量：
   • DATABASE_URL：PostgreSQL 连接串，格式 postgresql://用户名:密码@主机:端口/数据库名。
   • ADMIN_TOKEN：自定义字符串（如 mysecretadmin123），用于后台登录。
   示例：DATABASE_URL=postgresql://user:pass@dbhost:5432/mydb。

步骤 1：拉取镜像

打开终端，执行以下命令下载最新镜像：

docker pull janephpdev/zuzshorturl:latest

• 验证：运行 docker images 检查镜像是否存在。
• 潜在问题：网络超时？使用代理或重试。镜像大小约 200 MB，下载需 1-2 分钟。

步骤 2：运行容器

使用以下命令启动容器（替换占位符）：

docker run -d \
  --name zuzshorturl-app \
  -e DATABASE_URL=postgresql://<用户名>:<密码>@<主机>:<端口>/<数据库名> \
  -e ADMIN_TOKEN=<管理员令牌> \
  -p 8437:8437 \
  janephpdev/zuzshorturl:latest

• 参数详解：
  • -d：后台守护进程运行，避免阻塞终端。
  • --name：自定义容器名，便于后续管理（如 docker stop zuzshorturl-app）。
  • -e：注入环境变量，确保数据库连接和安全令牌生效。
  • -p 8437:8437：端口映射，将容器内 8437 端口暴露到宿主机。自定义端口示例：-p 8080:8437（访问 localhost:8080）。
• 最佳实践：为生产环境添加卷挂载持久化数据（如 -v /host/path:/var/www/data），但本项目数据主要存数据库，无需强制。
• 验证启动：运行 docker ps 检查容器状态为 "Up"。查看日志：docker logs zuzshorturl-app（排查错误，如连接失败）。

步骤 3：访问与初始化

1. 在浏览器打开 http://localhost:8437（或自定义端口）。您将看到短链接生成界面。
2. 执行数据库迁移（首次必须）：
   • 访问 http://localhost:8437/migrate。
   • 输入 ADMIN_TOKEN，点击“运行迁移”。
   • 成功后，自动重定向到 /admin 管理面板。
3. 测试功能：生成一个短链接，验证跳转和统计。

步骤 4：Nginx 反向代理（可选，推荐生产环境）

若需自定义域名或 HTTPS，使用 Nginx 代理容器端口。编辑 /etc/nginx/sites-available/default：

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:8437;
        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;
    }
}

• 重启 Nginx：sudo systemctl restart nginx。
• HTTPS 配置：使用 Certbot（Let's Encrypt）安装 SSL：sudo certbot --nginx。
• 提示：如果数据库在宿主机，DATABASE_URL 中的主机地址用公网 IP，而非 127.0.0.1（Docker 内 127.0.0.1 指容器自身）。

容器管理

• 停止/移除：docker stop zuzshorturl-app && docker rm zuzshorturl-app。
• 更新：docker pull janephpdev/zuzshorturl:latest，然后重新运行。
• 常见问题：
  • 端口冲突：更改 -p 参数。
  • 数据库连接失败：检查防火墙（允许 5432 端口）和凭证。

此方案部署时间 < 5 分钟，适合快速迭代。

Apache + PostgreSQL 部署方案

此方案适用于传统 VPS（如阿里云/腾讯云），使用 Apache 作为 Web 服务器。需手动配置虚拟主机和模块。

前提条件

• Apache 安装：Ubuntu/Debian：sudo apt install apache2；CentOS：sudo yum install httpd。
• PHP 8.3 + pdo_pgsql：sudo apt install php8.3 php8.3-pgsql（验证：php -m | grep pgsql）。
• PostgreSQL：参考后文准备。
• 项目文件：从 GitHub 克隆到 /var/www/zuzshorturl，运行目录为 /var/www/zuzshorturl/api。

步骤 1：准备 PostgreSQL 数据库

1. 安装 PostgreSQL（若未安装）：sudo apt install postgresql。
2. 以 postgres 用户登录：sudo -u postgres psql。
3. 执行 SQL 创建数据库和用户（替换占位符，如数据库名 zuz_db）：

   -- 创建数据库
   CREATE DATABASE zuz_db;
   
   -- 创建用户
   CREATE USER zuz_user WITH PASSWORD 'zuz_pass123';
   
   -- 授予数据库权限
   GRANT ALL PRIVILEGES ON DATABASE zuz_db TO zuz_user;
   
   -- 连接到数据库
   \c zuz_db
   
   -- 授予 Schema 权限（确保迁移可创建表）
   ALTER SCHEMA public OWNER TO zuz_user;
   GRANT ALL ON SCHEMA public TO zuz_user;
   

4. 退出：\q。

• 验证：psql -U zuz_user -d zuz_db -h localhost（输入密码）。
• 远程访问：编辑 /etc/postgresql/*/main/pg_hba.conf 添加 host all all 0.0.0.0/0 md5，重启：sudo systemctl restart postgresql。
• 最佳实践：使用强密码，避免 root 用户。生产环境启用 SSL。

步骤 2：配置 Apache 虚拟主机

1. 启用 SSL 站点：sudo a2ensite default-ssl（若需 HTTPS）。
2. 编辑站点配置文件（如 /etc/apache2/sites-available/000-default.conf）：

   <VirtualHost *:80>
       # 强制 HTTPS 重定向
       Redirect permanent / https://yourdomain.com/
   </VirtualHost>
   
   <VirtualHost *:443>
       SSLEngine on
       SSLCertificateFile /path/to/cert.pem  # Let's Encrypt 路径
       SSLCertificateKeyFile /path/to/privkey.pem
   
       DocumentRoot /var/www/zuzshorturl/api
   
       # 环境变量（使用英文注释避免解析错误）
       SetEnv DATABASE_URL "postgresql://zuz_user:zuz_pass123@localhost:5432/zuz_db"
       SetEnv ADMIN_TOKEN "mysecretadmin123"
   </VirtualHost>
   

3. 测试配置：sudo apache2ctl configtest（应输出 "Syntax OK"）。

• HTTPS 设置：使用 Certbot：sudo certbot --apache -d yourdomain.com。
• 潜在问题：域名未解析？检查 DNS 设置（A 记录指向服务器 IP）。

步骤 3：启用必要的 Apache 模块

运行以下命令：

sudo a2enmod rewrite  # 支持伪静态路由
sudo a2enmod env      # 处理环境变量
sudo systemctl restart apache2

• 验证：apache2ctl -M | grep rewrite（应显示启用）。
• 伪静态：项目内置 .htaccess 支持，无需额外配置。

步骤 4：设置文件权限

cd /var/www/zuzshorturl
sudo chown -R www-data:www-data .  # Apache 用户组
sudo chmod -R 755 .                # 目录可执行，文件可读

• 细化权限（生产推荐）：find . -type f -exec chmod 644 {} \;（PHP 文件 644）。
• 验证：ls -la 检查所有者。权限不足会导致 403 错误。

步骤 5：访问与初始化

1. 重启 Apache 后，访问 https://yourdomain.com。
2. 执行迁移：访问 /migrate，输入 Token，运行。

• 常见问题：
  • 连接失败：确认 pdo_pgsql 启用（php -i | grep pgsql）。
  • 权限错误：数据库用户需 CREATE 权限。

部署时间约 15-30 分钟，适合自定义优化。

环境变量配置

环境变量是项目安全核心，确保敏感信息不硬编码。格式：

DATABASE_URL="postgresql://用户名:密码@主机:端口/数据库名"
ADMIN_TOKEN="自定义令牌（至少 12 位）"

• 注入方式：Docker/Apache 使用 -e 或 SetEnv；Vercel 在仪表盘设置。
• 安全提示：令牌勿泄露，使用随机生成器创建。更改后重启服务。

本地测试

开发或调试时：

1. 克隆仓库：git clone https://github.com/JanePHPDev/ZuzShortURL.git。
2. 设置环境变量（.env 文件或导出）。
3. 运行内置服务器：cd ZuzShortURL && php -S localhost:8000 -t . api/index.php。
4. 访问 http://localhost:8000，执行迁移测试。

• Nginx/Apache 替代：设置根目录为 api/，启用 Rewrite 模块。
• 问题排查：日志在 /var/log/apache2/error.log。

数据库迁移详解

迁移初始化表（如 users、links），只需一次。前提：环境变量设置，用户有 CREATE 权限。

步骤：

1. 访问 /migrate。
2. 输入 ADMIN_TOKEN。
3. 点击“运行迁移”（执行 SQL 创建表、索引）。
4. 成功：重定向 /admin；失败：检查日志（权限/连接）。

故障排除：

• 权限不足：重跑 SQL 授予 CREATE。
• Token 无效：验证环境变量（echo $ADMIN_TOKEN）。
• 连接错误：测试 psql 命令。

Vercel 免费部署方案

适合零成本上线：

1. Fork 仓库。
2. 在 Vercel 导入项目。
3. 设置环境变量（仪表盘 > Settings > Environment Variables）。
4. 点击一键部署，部署后重新 Deploy。
5. 执行迁移（同上）。

• 限制：Vercel 与 PHP 冲突，二维码/活码功能暂不可用。
• 时间： < 2 分钟。

免费数据库方案：Supabase

Supabase 提供托管 PostgreSQL，免费额度充裕。

1. 注册 Supabase，创建 Project。
2. 导航到 Settings > Database > Connection String，选择 URI 格式 + Session Pooler。
3. 复制串（如 postgresql://postgres:***@aws-0-ap-southeast-1.pooler.supabase.com:5432/postgres）。
4. 粘贴到 DATABASE_URL，迁移自动处理（无需建表）。

• 额度：500 MB 存储，超出按量付费。
• 集成：完美适配 Vercel/Docker。