说明文档

接口功能

基础功能	对应字段	ps-API	adobe-API
文字图层内容修改	`new_contents`	✔️	✔️
文字图层字体修改	`new_fonts`	✔️	⛔（官方`API`限制，仅支持部分adobe的字体）
文字图层大小修改	`font_sizes`	✔️	✔️
智能对象图层文字内容修改	`new_contents`	✔️	⚠（官方`API`限制，通过多次调用实现）
智能对象图层文字字体修改	`new_fonts`	✔️	⛔（官方`API`限制，仅支持部分adobe的字体）
智能对象文字超边界修复	`font_sizes`	✔️	✔️
智能对象图层图片替换	`new_contents`	✔️	✔️
自定义尺寸：长、宽	`width`、`height`	✔️	✔️
自定义分辨率（DPI）	`dpi`	✔️	✔️
支持多种格式输出：`jpg`、`png`、`pdf`、`tiff`	`output_type`	✔️	✔️

接口已实现接口所有需求的所有功能
国内使用的话，ps-API对图图片处理较快
adobe-API对智能对象修改有一定局限性，部分需求通过调用多次实现，官方明确表示后续接口会增加该方面功能。
adobe-API需要用国外服务器部署，国内延迟非常大
官方支持的字体：https://github.com/AdobeDocs/photoshop-api-docs/blob/master/SupportedFonts.md

项目架构

目录结构

项目目录
  |-- data                # 关键数据存放目录
  |   |-- adobe           # 存放adobe账号后台对应的项目文件 config.json、private.key， 一个文件夹对应一个项目名  
  |   |-- bucket          # 存储桶相关key的文件，比如aws-s3的文件就有 new_user_credentials.csv、 rootkey.csv
  |   |-- psd             # psd 文件预处理后的存放文件夹
  |   `-- fonts           # psd文件所有第三方字体（需要手动另外安装到系统），接口会定期上传这里的字体到存储桶
  |-- docs                # 一些以往的说明文件
  |-- docker
  |   |-- web/            # docker
  |   |   |-- Dockerfile  # 
  |   |   `-- requirements.txt # docker 部署专用的requirements.txt
  |   |-- redis/          # 
  |   |   |-- data/       # redis容器挂载后的data目录
  |   |   `-- redis.conf  # docker挂载后映射的redis配置文件
  |   |-- build.sh        # 部署脚本
  |   |-- check.sh        # 环境检查脚本
  |   `-- docker-compose.yml # compose配置文件
  |-- logs                # 日志文件
  |-- src                 # 源码目录
  |   |-- modules         # module层，也可以当作是server层
  |   |-- tools           # 接口层面的工具函数
  |   |-- utils           # 关键的一些工具函数层
  |   |-- storages        # 存储桶层
  |   |-- routers         # 路由层     
  |   |   `-- v1          # 接口
  |   `-- static          # 所以文件都会上传到本文件夹
  |       |-- temp        # 临时文件夹，首次上传的文件都会存放到这里，处理后会自动删除，接口定期清理
  |       `-- upload      # 临时文件夹
  |--   config.py         # 次级的配置文件，最终以config.ini 为准
  `--   main.py           # 接口启动文件 启动命令：python3 main.py (工作目录确保为src目录)

关键目录

以下所有目录均可以在config.ini或者config.py内重新自定义，建议使用绝对路径明确指定

目录	作用	备注
`logs/*.log`	日志文件	以日期来存储
`data/adobe`	adobe的项目文件夹，新建文件夹即可动态的添加key	每个key每月限制5000次
`data/fonts`	第三方字体的文件夹，任何用到的字体都要直接拷贝到这里，然后重启接口即可
`data/psd`	所以预处理后的`psd`文件存放
`src/static`	静态服务器的根目录
`src/static/upload`	所有上传文件后首次存放的目录

关键文件

文件	说明	备注
`config.ini`	服务器关键配置	优先等级最高
`config.py`	服务器详细配置文件	优先等级紧接`config.ini`
`private.key`	通过adobe账号新建项目后获得	一个账号每月调用限制为5000
`xxxxxx(JWT).json`	通过adobe账号新建项目后获得	请注册多个账号获取多个key

配置文件

配置文件路径：{项目路径}/config.ini

配置示例：

等号两边建议带上一个空格，方便查看
一些开关类的属性使用 "on" | "off" 来表示

# config.ini 文件
app_name = xxxxx                 # 接口名称
default_engine = ps              # 优先调用本地ps还是adobe接口处理请求
domain = http://你的域名.xxx.xx   # 本地调用ps处理后的图片前缀，默认为空也可以
HAS_PS = on                      # 是否使用本地的ps处理请求
port = 80                        # 最终对外的端口 默认4040

psd_files_path = d:/abc/psd      # 将预处理的文件存放到 d盘的 abc下面的psd目录中
upload_path = d:/abc/upload      # 将上传的文件存放到 d盘的 abc下面的upload目录中

config.ini

config.ini管理整个接口的所有配置入口文件

# 基础格式
字段名 = 字段值

# config.ini 文件
# 开发模式（实际上线请设置为 off）
DEV = on
port = 4040

# 默认使用ps处理请求
default_engine = ps

# 完全关闭ps
PS_API_ENABLE = off

# 本地合成图片输出的前端部分url路径，建议设置为空即可
domain = ""

# 存储桶路径
bucket_url = ""
# 指定存储桶类型
bucket_type = "bunny"
# 存储桶key
bucket_api_key = ""

# 预处理后是否上传
pre_upload_psb_enable = on

基础配置

字段	说明	默认值	备注
`DEV`	调式模式，实际测试无问题后，请务必设置为off	`on`	`DEV = off`
`port`	接口的端口	`4040`	`port = 80`
`default_engine`	优先调用本地ps还是adobe接口处理请求	`ps`	`default_engine = adobe`
`PS_API_ENABLE`	是否启用`PS`总开关，设置为`off`，任何环境下都不会再调用本地`PS`	`on`	`PS_API_ENABLE= off`

关键目录

字段	说明	默认值	备注
`upload_path`	所有文件上传的目录，自动清理存放超过30天的文件	`{接口目录}/static/upload`	`d:/xxxx/upload`
`psd_files_path`	预处理关键目录	`{接口目录}/static/psd`	`d:/xxxx/psd`
`font_path`	字体文件本地存放的路径同时请确保系统也要手动安装	`{接口目录}/static/fonts`	`d:/xxxx/fonts`

字体文件存放到font_path后，每次接口启动都会扫描一次该目录并记录所有字体到数据库

存储桶相关

字段	说明	默认值	备注
`bucket_url`	完整的存储桶路径		`http://xxxx.xxx.com`
`bucket_type`	`bunny`、`aws-s3` 仅支持这两个	`aws-s3`
`bucket_api_key`	存储桶的访问密钥
`bucket_access_token`	存储桶的访问token，s3会有，bunny 不需要
`bucket_font_path`	存储桶上放字体的目录最终会与`bucket_url`拼接组成完整路径 `http://xxxx.xxx.com/fonts`	`fonts`
`bucket_img_upload`	存储桶图片上传的后存放的位置	`temp`
`bucket_psd_path`	存储桶预处理psd文件上传的位置	`psd`

adobe-api相关

字段	说明	默认值	备注
`adobe_token_expire`	token每7小时续期（官方有效期是24小时）	`25200`(7小时)	单位是秒
`adobe_config_path`	token 文件存放的目录，每7小时自动更新	`{接口上层目录}/data/adboe`	`adobe_config_path = d:/config/adboe`

预处理相关

字段	说明	默认值	备注
`pre_except_group`	预处理时忽略的图层组，明确设置可以加快预处理的速度	`["BG", "FG"]`
`pre_small_width`	预处理时，小尺寸文件的宽度，高度自动计算	`500`
`pre_medium_width`	预处理时，中尺寸文件的宽度，高度自动计算	`1000`
`pre_upload_psb_enable`	是否同步上传文件到存储桶	`off`	`pre_upload_psb_enable = on`
`pre_quality_enable`	是否生成 small、medium等小尺寸文件	`on`

字体相关的

字段	说明	默认值
`font_ext`	哪些后缀的文件被认作字体	`[".ttf", ".otf"]`
`font_path`	字体文件上传后保存的目录
`font_auto_upload`	字体是否自动上传存储桶

注意
请不要修改config.py，除非你明确了解它的作用，接口所有配置都以 config.ini 为准

并发处理

由于ps-API同一时间单位只能处理一个请求，要支持并发，可以采用多服务器部署方案。
默认情况接口会优先采用ps-API进行处理，如果处理途中有请求进入，请求会被放到等待队列中，等待1秒（参数可配置），1秒后无处理则会调用官方API处理。
通过修改config.default_engine，可以指定接口默认采用哪种方式处理请求，支持"ps"|"adobe"
因为当前并发处理实际只是转发请求，所以理论上adobe支持多少并发，接口就支持多少并发，唯一问题是官方API处理延迟大（国内），国外经测试至少还能比国内快1秒以上。
建议预处理的服务器硬盘空间要给够，经过处理后，最高会多占原来的4~5倍空间

添加Adobe`api-key`

由于一个账号每月限制调用次数为5000次，所以请注册多个账号，通过以下步骤将关键文件添加指定目录(config.adobe_config_path)中，建议目录名称与账号同名，这样比较好管理。

具体步骤

注册一个adobe官方账号
登陆账号，进入后台
下载config.zip文件内含（private.key）
下载xxxxxx(JWT).json文件

一、登陆账号，进入控制台

二、创建一个`photoshop-api`的项目，获取`private.key` 文件

官方的调用限制是以账号为单位的，所以需要注册多个账号，每个账号新建一个项目

选择 photoshop API

获得`private.key` 文件

三、得到 `config.zip`

将文件内的`private.key`存放到 `{项目目录}/data/adobe/新建一个项目名/private.key`

建议将文件夹的名称改为与项目账号名称一致，因为每个账号无论多少个项目都是共享调用次数的，一个账号相当于一个key

四、获取项目`xxxxxx(JWT).json`文件

将新下载的`(JWT).json`文件拷贝到`private.key`同一目录即可

五、更新数据到接口

方法1 ：手动重启接口
方法2 ：等待接口定时更新即可，默认7小时，可在config.py.adobe_token_expire字段来配置

六、修改配置文件的存放目录

config.ini 中修改 adobe_config_path字段： adobe_config_path = 你想要的目录

数据库

本接口仅采用了redis作数据库

数据库	说明
db0	存储桶相关数据，`api-api`、`access-token`
db1	psd预处理数据，图层类型
db3	字体相关

Adobe 权鉴数据

KEY	类型	说明
`{project_name}`	`string`

// {project_name}的项目数据结构
{
  // 小写key部分
  "project_name":"psd-tools", // 项目名
  "count":"4800",             // 该key已经使用的次数
  "create_time":"1656034078", // 该key创建的时间
  "access_token":"xxxxxxxxx", // 未添加Bearer 的jwt-token
  
  // 大写key部分：完全对应 xxx(JWT).json 的内容，该文件通过官网项目下载
  "CLIENT_SECRET": "p8e-m0NLC7Jyh4PdxK6LXMI4Qm5OD-tS1lTF",
  "ORG_ID": "3CC3266C626B9B030A495F8A@AdobeOrg",
  "API_KEY": "daa0f550d4c641f68e08d1d74fcf594f",
  "TECHNICAL_ACCOUNT_ID": "55C94A89628B83F50A495F9C@techacct.adobe.com",
  "TECHNICAL_ACCOUNT_EMAIL": "61a86121-6c3f-48fb-836d-3113b1436931@techacct.adobe.com",
}

字体数据

KEY	类型	说明
`FONT:{font_name}`	`Hash Table`	每个字体的详细数据

psd预处理数据

KEY	类型	说明
`{file_name}`	`string:json`	对应预处理后的.info文件
`RECEN_PROJECT_NAME`	`string`	最近一次使用的项目`key`数据

// FONT:{font_name} 的数据格式
{
    "font_name":str,
    "font_url":"xxxx", // 字体位于存储桶链接
}

预处理.info文件格式

{
    "file_name": "1-2.psd",
    "file_ext": ".psd",
    "file_path": "W:\\CPS\\MyProject\\python-tools\\ps-tools\\src\\static\\psd\\1-2.psd\\1-2.psd",
    "file_size": "18.01mb",
    "file_len": 18880279,
    "group_list": [
        "DYNAMIC "
    ],
    "layer_list": [
        "Background copy 拷贝 2",
        "背景"
    ],
    "width": 2000,
    "height": 2000,
    "layer_count": 3,
    "FONT_LIST":["字体名称"],
    "TEXT_LAYERS_INFO": [
        {
            "layer_name": "__D__",
            "layer_type": "text",
            "text_content": "88",
            "has_mask": false,
            "text_raw": "88\r",
            "layer_id": 7,
            "font_name": "2019ProBowl",
            "font_size": 443.59
        },{.../}
    ],
    "SMART_LAYERS_INFO": [
        {
            "layer_name": "__C__",
            "layer_id": 69,
            "layers": [
                {
                    "layer_name": "TRUBISKY",
                    "layer_kind": "文字图层",
                    "visible": true,
                    "has_mask": false,
                    "layer_id": 70,
                    "layer_type": "text",
                    "text_content": "TRUBISKY",
                    "text_raw": "TRUBISKY\r",
                    "font_name": "2019ProBowl",
                    "font_size": 180.0
                }
            ],
            "layer_count": 1,
            "layer_type": "smart_text",
            "change_type": "text",
            "inside_layer_name": "TRUBISKY",
            "inside_layer_id": 70,
            "max_text_len": 8,
            "font_list": [
                "2019ProBowl"
            ],
            "psb_path": "W:\\CPS\\MyProject\\python-tools\\ps-tools\\src\\static\\psd\\1-2.psd\\DYNAMIC __C__.psb",
            "psb_linked": false,
            "psb_name": "__C__.psb"
        }
    ]
}

预处理

PSD文件

linux 环境下，因为无法调用ps，所以不会进行预处理

文件	说明	是否上传	备注
backup.psd	原始文件	⛔
1-2.psd	优化后的原始尺寸文件	✔️
1-2_small.psd	小尺寸的设计文件（500x500）	✔️	可修改： `config.pre_small_width` 字段自定义
1-2_medium.psd	中尺寸的设计文件（1000x1000）	✔️	中尺寸固定是小尺寸的两倍
1-2.psd_backup	优化后的原始尺寸文件的备份	⛔
图层组_图层名.psb	智能对象图层文件	✔️	用于给官方api修改智能对象字体内容时使用
图层组_图层名.psb_backup	智能对象图层文件的备份	⛔
1-2.psd.info	json格式的文件预处理数据	⛔	保存在本地和数据库各一份

预处理后，本地文件大概会比原来大4~5倍
上传部分的文件一般是源文件的2倍

服务器配置

测试服务器配置

硬件	型号	规格
CPU	Inter i7-6820HQ （Thinkpad p50移动工作站）	3.2Ghz 四核八线程
内存	16G
硬盘	SSD 固态（M.2 NGFF SATA协议2280）
显卡	NVIDIA Quadro M1000M

云服务器器配置（建议）

硬件	型号规格	备注
CPU	3.0Ghz 以上 3核以上	photoshop软件比较吃cpu主频，频越高处理越快
内存	8GB以上	新版的photoshop 最低8G才能对当前的文件流畅处理
硬盘	NVMe	硬盘影响文件打开速度

vultr 建议方案

高主频的cpu
内存大于8GB
硬盘越快越好

方案1

方案2

文件上传

接口支持任意文件上传，目前仅以文件后缀来区分文件名，没做太深入的文件验证

.psd、.psb 文件上传后会调用预处理，同时上传到存储桶
字体文件需要通过上传接口上传后，接口会自动上传到对应的存储桶
图片文件一般上传的目的是用来替换psd内的某一图层，接口会定期清理存在超过30天的图片文件

支持的文件格式	上传后保存的目录	存储桶路径
.psd、.psb	`config.pre_path`	`config.bucket_psd_path`
.ttf、.otf	`config.font_path`	`config.bucket_font_path`
.jpg、.jpeg、.png、.bmp、.ttf	`config.temp_path`	`config.bucket_img_upload`

注意事项【重要】

所有psd、图片等文件不要采用空格命名，或者过长的命名。
如果遇到缺少的字体，photoshop软件会被卡住，导致接口无法继续预处理，此时请手动关闭缺少字体提示和文件，重启接口
- 如果ps卡住，此时接口无法再处理任何文件上传和预处理，但是可以调用adobe进行图片合成和修改
后续adobe可能会更新支持外链智能对象和修改智能对象文字的功能
请确保本系统中只有一个版本的Photoshop
请确保字体文件的名字与ps内选择该字体时显示的名称保持一致
- 字体文件原名：CVB__123117.ttf
- PS软件内选择名为：Cvb-123117
- 请将名字改为：Cvb-123117.ttf

接口功能​

项目架构​

目录结构​

关键目录​

关键文件​

配置文件​

config.ini​

基础配置​

关键目录​

存储桶相关​

adobe-api相关​

预处理相关​

字体相关的​

注意​

并发处理​

添加Adobeapi-key​

具体步骤​

一、登陆账号，进入控制台​

二、创建一个photoshop-api的项目，获取private.key 文件​

选择 photoshop API​

获得private.key 文件​

三、得到 config.zip​

将文件内的private.key存放到 {项目目录}/data/adobe/新建一个项目名/private.key​

建议将文件夹的名称改为与项目账号名称一致，因为每个账号无论多少个项目都是共享调用次数的，一个账号相当于一个key​

四、获取项目xxxxxx(JWT).json文件​

将新下载的(JWT).json文件拷贝到private.key同一目录即可​

五、更新数据到接口​

六、修改配置文件的存放目录​

数据库​

Adobe 权鉴数据​

字体数据​

psd预处理数据​

预处理​

PSD文件​

服务器配置​

测试服务器配置​

云服务器器配置（建议）​

vultr 建议方案​

方案1​

方案2​

文件上传​

注意事项【重要】​

接口功能

项目架构

目录结构

关键目录

关键文件

配置文件

config.ini

基础配置

关键目录

存储桶相关

adobe-api相关

预处理相关

字体相关的

注意

并发处理

添加Adobe`api-key`

具体步骤

一、登陆账号，进入控制台

二、创建一个`photoshop-api`的项目，获取`private.key` 文件

选择 photoshop API

获得`private.key` 文件

三、得到 `config.zip`

将文件内的`private.key`存放到 `{项目目录}/data/adobe/新建一个项目名/private.key`

建议将文件夹的名称改为与项目账号名称一致，因为每个账号无论多少个项目都是共享调用次数的，一个账号相当于一个key

四、获取项目`xxxxxx(JWT).json`文件

将新下载的`(JWT).json`文件拷贝到`private.key`同一目录即可

五、更新数据到接口

六、修改配置文件的存放目录

数据库

Adobe 权鉴数据

字体数据

psd预处理数据

预处理

PSD文件

服务器配置

测试服务器配置

云服务器器配置（建议）

vultr 建议方案

方案1

方案2

文件上传

注意事项【重要】