EspoCRM 从零到生产完整部署与调优实战【免费下载链接】espocrmEspoCRM – Open Source CRM Application项目地址: https://gitcode.com/GitHub_Trending/es/espocrmEspoCRM 是一款免费开源的 CRM 系统把线索、联系人、商机、市场活动、支持工单这些客户关系管理里的核心环节装进同一套界面。从线索捕获到商机推进从邮件收发到批量群发从报表导出到门户前台你不需要拼凑多个工具就能跑通一套完整的客户管理流程。它的两个差异化卖点很实在一是元数据驱动自定义实体和字段不用碰底层代码改 JSON 就能生效二是自带标准 REST API任何外部系统都能用 token 直接读写数据。本文带你从装好 PHP 开始走完首装、配置、调优和日常运维的全流程。环境速查装之前先过这一关运行前提一览项目要求说明PHP8.3 – 8.5硬门槛低于 8.3 安装向导直接卡住数据库MySQL 8.0 / MariaDB 10.6 / PostgreSQL 15三选一按platform参数切换Web 服务器Apache 2.4 或 Nginx必须启用 URL 重写PHP 扩展openssl、json、zip、gd、mbstring、xml、dom、curl、exif、pdo、ctype另建议装 bcmath、pdo_mysql 或 pdo_pgsql、fileinfo、pcntl资源内存 ≥ 512MB磁盘 ≥ 200MB附件和日志会持续占用data/空间所有配置项和版本下限都能在安装器源码里查证见 install/core/。装完后用一条命令核对扩展是否齐php -m | grep -E openssl|json|zip|gd|mbstring|xml|dom|curl|exif|pdo|bcmathPHP 参数建议值来自仓库自带的recommendedPhpParamsmemory_limit256M、max_execution_time180、post_max_size20M、upload_max_filesize20M。上传大附件时再把upload_max_filesize调上去否则前端分片上传会在后端被截断。从 0 到跑通获取代码、配服务、走完向导1. 获取代码。二选一git 克隆git clone https://gitcode.com/GitHub_Trending/es/espocrm cd espocrm或直接下载官网发布的 release 包解压到站点目录。源码方式多一步依赖安装composer install2. 配 Web 服务器。站点根目录指向仓库根目录入口是public/index.php和public/api/v1/index.php。Nginx 下安装器自带的参考配置节选自 install/core/config.phpserver { listen 80; root /var/www/espocrm/public; location / { try_files $uri $uri/ /index.php?$query_string; } location /api/v1/ { if (!-e $request_filename) { rewrite ^/api/v1/(.*)$ /api/v1/index.php last; break; } } location ^~ /data/ { deny all; } location ^~ /application/ { deny all; } location ^~ /custom/ { deny all; } }Apache 则启用 rewrite 模块并给站点目录AllowOverride All。deny all这几行别省data/里存着数据库密码application/是可读源码直接暴露等于裸奔。3. 准备数据库。建一个空库和专用账号安装向导只写数据、不会替你建库mysql -u root -p -e CREATE DATABASE espocrm DEFAULT CHARSET utf8mb4; \ CREATE USER espocrmlocalhost IDENTIFIED BY YourStrongPass; \ GRANT ALL ON espocrm.* TO espocrmlocalhost;安装完成后的连接信息落在data/config.php的database键下host、port、dbname、user、password默认值定义在 application/Espo/Resources/defaults/config.php。4. 走安装向导。浏览器访问站点根路径按编号走完五步确认许可勾选同意 GNU AGPLv3 条款。系统自检自动验证 PHP 版本、必备扩展和目录写权限报 Permission denied 时页面会直接给出要执行的chown/chmod命令照做即可。数据库连接填platformMysql/Postgresql、库名、主机端口、账号密码向导会先试连再落库。创建管理员设置用户名和密码这是全站第一个账号务必记牢。完成配置系统自动建表并重建元数据最后页面会输出一行 cron 配置提示把它抄下来。5. 挂上 cron。定时任务、邮件拉取、清理作业都靠它驱动缺了 cron 邮件功能等于半瘫* * * * * php /var/www/espocrm/command.php cron /dev/null 21拆解技术底座为什么它改起来不费劲架构形态很直接前端是基于自研框架的单页应用核心部分用 TypeScript 编写嵌套视图加服务注入通过 REST API 与 PHP 后端通信传输 JSON后端跑在 Apache 或 Nginx PHP-FPM 之上长任务交给command.php命令行和daemon.php常驻进程。最值得记住的一点是元数据驱动实体字段、布局、权限规则全部用 JSON 定义并带 JSON SchemaIDE 里有完整自动补全定制时多数情况只改配置不写代码。技术栈一览组件选型一句话理由前端自研 SPA 框架JS/TS嵌套视图复用高表单和字段视图现成API 框架PHP 8.3Slim 4 Symfony 组件REST 路由清晰静态类型 接口约束数据访问自研 ORMEspo\ORM基于 PDO跨 MySQL/PostgreSQL带查询构建器元数据JSON JSON Schema定义即文档改配置即改行为日志/邮件Monolog、Symfony Mailer轮转日志、SMTP 收发开箱即用任务队列自研 Job 表 后台 Workercron 触发支持并行进程核心目录速览application/Espo/ ├── Core/ # 框架内核DI 容器、ORM、HTTP、缓存 ├── Controllers/ # 每个实体的 REST 控制器 ├── Entities/ # 实体类映射数据库表 ├── Services/ # 业务服务层 ├── Repositories/# 数据访问封装 └── Resources/ # 元数据、布局、模板、i18n定制主战场 client/src/ # 前端 SPA 源码 custom/ # 自定义模块与代码升级不覆盖 data/ # 配置、日志、缓存、上传文件需可写 install/core/ # 安装向导实现核心能力实战三个最能体现价值的功能用元数据改字段不写一行 PHP要改哪个实体就改哪个 JSON路径固定Resources/metadata/下按实体分文件内置模块在application/自定义模块落在custom/下。给一个自定义实体加字段只需写{ fields: { customField: { type: varchar, maxLength: 100, required: true } }, links: { accounts: { type: hasMany, entity: Account } } }保存后跑一次重建即可全端生效php /var/www/espocrm/rebuild.php -m布局文件同在Resources/layouts/权限定义在acl.json全部同构IDE 补全直接可用。REST API 集成token 一贴就能调登录接口签发 token 后所有读写都是标准 RESTcurl -X POST https://crm.example.com/api/v1/Authenticate \ -H Content-Type: application/json \ -d {userName:admin,password:YourPassword}带 token 查询和创建curl -H X-User-Token: $TOKEN \ https://crm.example.com/api/v1/Contact?where[{\attribute\:\firstName\,\value\:\John\}] curl -X POST -H X-User-Token: $TOKEN -H Content-Type: application/json \ -d {firstName:John,emailAddress:john.doeexample.com} \ https://crm.example.com/api/v1/LeadCRUD 方法与权限动作的映射写在systemConfig的crud键里get→read、post→create、put→update……所以 API 行为和界面权限完全一致不存在界面看得到、接口读不到的灰色地带。公式驱动的工作流自动化公式Formula是独立子系统条件命中后执行动作典型结构如下{ entityType: Opportunity, conditions: [ { type: equals, attribute: stage, value: Closed Won } ], actions: [ { type: createRecord, entityType: Task, fields: { name: Follow up with customer } } ] }后端实现在 application/Espo/Core/Formula/200 类application/Espo/Classes/Formula/和Tools/Formula/分别放定义处理和工具类配合Hooks/目录的实体钩子审批、分配、通知这类流程都能配置化落地。生产加固清单上线前逐项打勾性能侧开启 OPcacheopcache.validate_timestamps生产设为 0revalidate_freq调到 2–5 秒配合clear_cache.php手动清。元数据和布局走data/cache/文件缓存useCache默认 true 不要关大并发实例可评估仓库已引入的 predisRedis 客户端方案。后台任务并发jobPoolConcurrencyNumber默认 8 进程机器富余再往上加单次任务超时由jobPeriod默认 7800 秒兜底超时任务标记 Failed。数据库层面用 ORM 查询构建器拼条件别在业务代码里手拼 SQL大表查询走whereselect白名单字段避免全列拖回。安全侧全站 HTTPSdata/config.php权限收紧chmod 600 /var/www/espocrm/data/config.php失败登录有内置限流参数authMaxFailedAttemptNumber、authUsernameFailedAttemptsPeriod等见systemConfig.php默认即生效不要清零。需要时把authIpAddressCheck置 true 并配authIpAddressWhitelist把管理端收敛到内网段。审计链路两条操作审计在ActionHistory日志落data/logs/espo.log默认 WARNING 级轮转保留 30 份均在logger配置段排障临时把level调到 DEBUGprintTrace打开查完改回。Web 层按前面 Nginx 片段deny all掉data/、application/、custom/、vendor/前端 CSP 默认开启clientCspDisabled为 false别为了嵌第三方脚本关掉。日常运维手册日志、监控与备份日志位置应用日志data/logs/espo.logPHP 错误日志走 PHP-FPM/Apache 自己的配置Web 访问日志在站点access.log。常用监控命令tail -f /var/www/espocrm/data/logs/espo.log # 实时看应用日志 ps aux | grep -E command.php|daemon.php # 确认 cron/常驻进程活着 mysqladmin -u espocrm -p processlist # 观察数据库连接堆积一键备份脚本数据库 文件保留 7 天#!/bin/bash BACKUP_DIR/backup/espocrm; DATE$(date %Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR mysqldump -u espocrm -pYourStrongPass espocrm $BACKUP_DIR/espocrm_db_$DATE.sql tar -czf $BACKUP_DIR/espocrm_files_$DATE.tar.gz -C /var/www espocrm find $BACKUP_DIR -type f -mtime 7 -delete恢复就是反操作mysql -u espocrm -p espocrm xxx.sql回灌数据库解包文件覆盖站点再跑php rebuild.php重建缓存和元数据。高频故障对照页面 404 / API 全部 404 → 重写未生效 →a2enmod rewrite systemctl restart apache2或检查 Nginx 的try_files。向导报 Permission denied →data/、custom/、client/custom/不可写 →chown -R www-data:www-data /var/www/espocrm find /var/www/espocrm/data -type d -exec chmod 755 {} \;。装库时报 PHP 版本不达标 → 多 PHP 版本共存时 FPM 指错了池 → 把站点fastcgi_pass指向 8.3 的 socket。500 且日志里是Class not found→ 依赖缺失 →composer install。邮件一直收不到 → cron 没挂或没跑 →crontab -l检查手动跑一次php command.php cron看输出。生态与进阶在 custom/ 里长出新模块所有定制代码都进custom/升级主程序不会覆盖它。一个新模块的骨架custom/Espo/Modules/YourModule/ ├── Entities/ # 实体类 ├── Controllers/ # REST 控制器 ├── Services/ # 服务 ├── Hooks/ # 实体钩子 └── Resources/ ├── metadata/ # 字段与链接定义 ├── layouts/ # 布局 └── i18n/ # 翻译最小的 PHP 侧示例继承实体基类即可被框架识别namespace Espo\Modules\YourModule\Entities; use Espo\ORM\Entity; class CustomRecord extends Entity { public const ENTITY_TYPE CustomRecord; }元数据照前面的 JSON 格式写进模块的Resources/metadata/重建后实体、API 端点、界面视图一起出现。前端视图放client/src/views/对应的模块路径下。想读懂框架本身建议按 README 的建议从依赖注入讲起application/Espo/Core/ 下Di/、Container/就是全部答案命令行工具实现在 application/Espo/Classes/ConsoleCommands/create-admin-user、set-password、db-check都在Resources/metadata/app/consoleCommands.json注册。社区交流走官方论坛开发文档见 docs.espocrm.com 的 development 栏目。写在最后EspoCRM 把可定制做成了架构级承诺元数据管界面和字段ORM 管存储custom/管你的代码三层互不纠缠。按本文走完你手里应该有一个带 cron、配好权限、日志可查的生产实例。下一步建议先接入真实数据源用 Import 批量导入客户再挂一个定时 Job 做增量同步。给自己开一块沙盒在custom/建第一个自定义实体跑通定义 → rebuild → 界面出现的完整链路。配置对外集成签发 API token让现有业务系统按 REST 规范读写 CRM。把备份脚本和 cron 状态纳入监控data/logs/espo.log接入告警。CRM 的价值随数据积累复利式增长——现在把地基打牢后面每多一个字段、每条工作流都是在给这条曲线加码。【免费下载链接】espocrmEspoCRM – Open Source CRM Application项目地址: https://gitcode.com/GitHub_Trending/es/espocrm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考