部署安装教程

本文档将指引你完成 PicGen 的完整安装部署流程，从环境准备到后台配置一步到位。推荐使用宝塔面板部署，3 分钟即可完成。

环境要求

必备环境

PHP 扩展

建议的 PHP 配置

upload_max_filesize = 20M
post_max_size = 30M
max_execution_time = 300
memory_limit = 256M

宝塔面板安装

推荐使用宝塔面板部署 PicGen，以下为完整步骤。

location / {
    try_files $uri $uri/ $uri.php$is_args$args;
}

location ~* ^/uploads/.*\.(php|php5|phtml|phar)$ {
    deny all;
}

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME}.php -f
RewriteRule ^(.+)$ $1.php [L,QSA]

手动安装

如果不使用宝塔面板，可以按以下步骤手动安装：

Worker 配置

后台图片生成依赖 Worker 进程，需要常驻运行。

命令行测试

先手动执行一次验证 Worker 是否正常：

php worker/generate_worker.php --once

如果能成功处理任务，说明可以将其设为常驻进程。

宝塔 Supervisor（推荐）

在宝塔「软件商店」安装 Supervisor 管理器，添加守护进程：

php worker/generate_worker.php

systemd（手动服务器）

[Unit]
Description=PicGen Generate Worker
After=network.target mysql.service

[Service]
Type=simple
WorkingDirectory=/www/wwwroot/picgen
ExecStart=/usr/bin/php /www/wwwroot/picgen/worker/generate_worker.php
Restart=always
RestartSec=5
User=www
Group=www

[Install]
WantedBy=multi-user.target

创建后执行：

systemctl daemon-reload
systemctl enable picgen-worker
systemctl start picgen-worker
systemctl status picgen-worker

Worker 状态与日志

后台配置简述

安装完成后登录 /admin/settings，以下是关键配置项。

图片接口

运行配置

云存储配置

系统支持三种图片存储方式：本地文件、数据库 base64、云存储。生产环境推荐使用云存储。

云存储支持：阿里云 OSS、腾讯云 COS、七牛云 Kodo。

通用字段

腾讯云 COS 详细配置

需要填写：

云存储服务商：腾讯云 COS
Bucket：imgcontent-1252487857（完整名，含 APPID）
Region：ap-guangzhou
AccessKey：SecretId
SecretKey：SecretKey
访问域名：你的 COS 默认域名或 CDN 域名

各字段在哪里查看：

• Bucket：腾讯云控制台 → 对象存储 COS → 存储桶列表 → 复制完整 Bucket 名（含 APPID）。后台不要单独填 APPID，直接填完整名。
• Region：存储桶列表中查看地域，常见 ap-guangzhou、ap-shanghai、ap-beijing。
• SecretId / SecretKey：右上角头像 → 访问管理 → 访问密钥 → 创建或查看 API 密钥。SecretId 填 AccessKey，SecretKey 填 SecretKey。
• 访问域名：进入存储桶 → 域名与传输管理 → 查看默认域名或 CDN 域名。默认形如 imgcontent-1252487857.cos.ap-guangzhou.myqcloud.com。

阿里云 OSS 详细配置

需要填写：

云存储服务商：阿里云 OSS
Bucket：my-image-bucket
Region：cn-hangzhou
AccessKey：AccessKey ID
SecretKey：AccessKey Secret
访问域名：你的 OSS 默认域名或 CDN 域名

各字段在哪里查看：

• Bucket：阿里云控制台 → 对象存储 OSS → Bucket 列表 → 复制 Bucket 名。
• Region：Bucket 详情 → 概览 → 查看地域。常见 cn-hangzhou、cn-shanghai、cn-beijing。
• AccessKey：右上角头像 → AccessKey 管理 → 创建或查看。ID 填 AccessKey，Secret 填 SecretKey。
• 访问域名：Bucket 详情 → 域名管理。默认形如 my-image-bucket.oss-cn-hangzhou.aliyuncs.com。

七牛云 Kodo 详细配置

需要填写：

云存储服务商：七牛云 Kodo
Bucket：空间名称
Region：z0（z0/z1/z2/na0/as0）
AccessKey：AccessKey
SecretKey：SecretKey
访问域名：空间绑定域名或 CDN 域名
七牛上传地址：上传区域地址

各字段在哪里查看：

• Bucket：七牛云控制台 → 对象存储 Kodo → 空间管理 → 复制空间名称。
• AccessKey / SecretKey：右上角头像 → 密钥管理 → 查看或创建。
• 访问域名：空间详情 → 域名管理 → 填写已绑定域名。
• 上传地址：取决于空间区域。华东 https://upload.qiniup.com，华北 https://upload-z1.qiniup.com，华南 https://upload-z2.qiniup.com，北美 https://upload-na0.qiniup.com，东南亚 https://upload-as0.qiniup.com。

建议权限

建议为云存储单独创建子账号或子用户，只授予目标 Bucket / 空间的上传权限，不要使用主账号长期密钥。

配置保存位置

云存储配置保存到 config/cloud_storage.php，不会写入数据库。

外观主题

支持预设主题和自定义主题色、Logo、底部版权 HTML。选择自定义后可直接调整颜色，纯色或渐变皆可。

安装后事项

常见问题

/login 或 /admin/settings 返回 404

优先检查两件事：站点根目录是否指向 public/；Nginx / Apache 是否已配置伪静态重写。

图片一直排队中

通常是 Worker 没有运行。先执行 php worker/generate_worker.php --once 测试，如果能处理就说明需要把 Worker 设为常驻进程。

短信验证码发不出去

• 后台短信/实名接口根地址是否正确
• UID 和密钥是否正确
• 接口账户余额是否充足
• 60 秒冷却是否命中
• 查看 worker/logs/sms.log

邮箱验证码发不出去

• SMTP Host、端口、加密方式是否匹配
• 是否填写了邮箱服务商的客户端授权码而非网页登录密码
• 服务器是否能连通 SMTP 端口
• 查看 worker/logs/mail.log

在线充值创建订单失败

• 是否开启在线充值
• 是否至少开启了一个支付方式
• 微信或支付宝必填字段是否完整
• 自定义金额关闭时，是否至少存在一个启用套餐

支付通道连接失败

• 服务器是否能访问微信支付或支付宝网关
• 支付宝当面付端口是否可达
• API Key、证书、私钥是否匹配正确
• 支付平台后台回调域名是否配置正确（生产建议 HTTPS）

实名认证提示失败

• 当前账号是否已绑定手机号
• 接口根地址、UID、密钥是否正确
• 是否满足成功判定：status = success、detect_result.status = 1、detect_result.check = 1

安装完成后提示「系统已安装」

这是正常的安全机制。请删除 public/setup.php 以完成收尾。