EspoCRM 部署指南：30分钟从零上线你的开源CRM系统

EspoCRM 部署指南：30分钟从零上线你的开源CRM系统

【免费下载链接】espocrmEspoCRM – Open Source CRM Application项目地址: https://gitcode.com/GitHub_Trending/es/espocrm

EspoCRM 部署指南：面向中小团队与开发者的开源客户关系管理系统，帮你把线索、客户、商机、市场活动统一到一个平台。本指南按环境预检、部署实操、避坑排查、生产优化四步走，约30分钟完成部署。

项目档案：EspoCRM 是什么、由什么构成

这一节用30秒帮你建立对项目的整体认知，后面所有操作都建立在这个技术底子上。

技术栈：

• 语言与运行时：PHP 8.3 ~ 8.5（后端基于 Slim 4 框架构建 REST 接口）
• 数据库：MySQL 8.0+/MariaDB 10.6+/PostgreSQL 15+（三选一）
• Web 服务器：Apache 或 Nginx，需要支持 URL 重写
• 前端：单页应用（SPA），自定义框架 + Backbone，核心部分使用 TypeScript
• 许可证：AGPL-3.0

架构特点：

• 前后端分离：前端是 SPA，后端提供完整的REST API，方便与外部系统对接
• 模块化：标准实体定义在 application/Espo/Modules/，你自己的扩展全部落在custom/目录（如 custom/Espo/Modules/），升级不冲突
• 元数据驱动：字段、布局、权限等大量配置以 JSON 元数据描述，改行为往往只需改配置

核心价值：你得到的是一个可以随意定制的"业务应用平台"——不只是管客户，还能自建实体、字段、按钮和工作流，界面保持简洁，上手成本低。

环境预检：部署前的自检清单

先花2分钟确认服务器底子，能省掉后面80%的排查时间。

组件与最低/推荐配置：

PHP 扩展要求（来自 composer.json 的系统要求）：

• 必需：pdo、json、openssl、mbstring、zip、gd、iconv、xml、dom、curl
• 推荐：exif、ctype、bcmath
• 数据库驱动：MySQL/MariaDB 用pdo_mysql，PostgreSQL 用pdo_pgsql

一键自检脚本，在仓库根目录直接运行：

#!/bin/bash # 1. PHP 版本 echo "== PHP 版本 ==" php -v | head -1 # 2. 必需扩展逐个检查 echo "== 扩展检查 ==" for ext in pdo pdo_mysql json openssl mbstring zip gd iconv xml dom curl; do php -m | grep -qi "^$ext$" && echo "OK $ext" || echo "MISS $ext" done # 3. 可写目录检查（安装向导会往这些目录写文件） echo "== 目录可写性 ==" for d in data custom client/custom; do touch "$d/.write_test" 2>/dev/null && rm -f "$d/.write_test" && echo "OK $d" || echo "FAIL $d 需要写入权限" done

⚠ 只要出现任何一个MISS或FAIL，先补齐再往下走：装扩展用系统包管理器（如apt install php8.3-xml php8.3-zip），目录权限问题看部署阶段的权限命令。

部署实操：三个阶段完成安装

整个安装就是三件事：拿代码、配 Web 入口、跑安装向导。逐个来。

阶段一：拉取代码并赋权

git clone https://gitcode.com/GitHub_Trending/es/espocrm cd espocrm # 统一基础权限 chmod -R 755 . # 这三个目录必须可写：安装配置、缓存、日志都落在 data/ chmod -R 775 data custom client/custom

关键前提：data/、custom/、client/custom/的属主必须是 Web 服务器运行用户（Apache 下通常是www-data，Nginx+PHP-FPM 下是www-data或nginx）。属主不对，安装向导会在权限检查这一步直接报Bad init Permission并中止。

阶段二：配置 Web 入口（重定向到 public/）

EspoCRM 的文档根目录必须指向public/目录，而不是仓库根目录。根目录的.htaccess和web.config会做重定向兜底，但直接配好最干净。

Apache（虚拟主机配置）：

<VirtualHost *:80> DocumentRoot /var/www/espocrm/public <Directory /var/www/espocrm/public> AllowOverride All Require all granted </Directory> </VirtualHost>

别忘了先a2enmod rewrite并重启 Apache。

Nginx（server块内）：

location / { try_files $uri $uri/ /index.php?$query_string; } client_max_body_size 50M;

root同样指向/var/www/espocrm/public，location ~ \.php$交给fastcgi_pass转发 PHP-FPM。

阶段三：运行安装向导

浏览器访问你的域名（例如http://crm.example.com），安装向导会自动启动，按页面顺序推进：

1. 同意许可证（AGPL-3.0 协议）
2. 选择语言与主题
3. 填写数据库：平台（MySQL/MariaDB/PostgreSQL）、主机（可带端口，如127.0.0.1:3306）、库名、用户名、密码
4. 保存偏好设置
5. 创建管理员账户，向导随后自动建库、建表、写data/config.php

克隆代码 → 赋权 data/custom → 配置 Web 根目录指向 public/ ↓ ↓ ↓ git clone chmod 775 Apache: AllowOverride All ↓ Nginx: try_files /index.php 浏览器访问域名 → 同意协议 → 选语言主题 → 填数据库 → 建管理员 → 建库建表 → 完成

验证与上线：怎么确认装成功了

装完别急着用，按下面5个检查点逐项过一遍，全部通过才算真正上线。

1. 首次登录：用向导创建的管理员账号登录，能看到仪表盘（含商机阶段图表）即主流程正常
2. 基础 CRUD 点验：新建一个 Contact，再建一个 Opportunity 并关联该客户，保存后刷新确认数据仍在
3. REST API 探活：未带凭据请求接口应返回鉴权拦截（说明 API 路由已生效）：

curl -i http://crm.example.com/api/v1 # 预期：401/403 一类的鉴权响应，而不是 404

4. 配置落盘检查：

ls -l data/config.php # 应存在 mysql -u<user> -p -e "show databases" # 应能看到你建的库

5. 定时任务就绪：EspoCRM 的后台作业（邮件同步、计划任务等）依赖 cron 每分钟触发cron.php，上线前就配好：

* * * * * php /var/www/espocrm/cron.php >/dev/null 2>&1

高频坑问答：四个最典型的故障现场

按出现频率排了序，每个都给你能直接执行的排查动作。

坑一：访问空白页或 500 错误

症状描述：浏览器打开域名，白屏、500，或者提示 PHP 版本不满足要求。

原因分析：最常见是 PHP 版本不在 8.3~8.5 区间、必需扩展缺失，或 Web 用户无权读文件。

解决方案：

1. php -v确认版本在 8.3~8.5 内；跑上面"环境预检"的扩展检查，补齐所有MISS项
2. 看 PHP 错误日志定位具体报错：tail -50 /var/log/php*-error.log（路径随发行版略有差异）
3. 确认 Web 服务器能读到代码：sudo -u www-data cat /var/www/espocrm/public/index.php | head -3，无权限报错即正常
4. 修完扩展或权限后systemctl restart apache2（或systemctl restart php8.3-fpm）再刷新

坑二：数据库连接失败

症状描述：向导填完数据库信息后报连接失败，卡在数据库步骤无法前进。

原因分析：凭证/主机/端口写错、数据库用户无建表权限，或 PHP 装的是pdo_mysql而你填的是 PostgreSQL（驱动不匹配）。

解决方案：

1. 用命令行按向导里填的同一套参数验证：mysql -h <host> -u <user> -p，能登进来才说明凭证没问题
2. 建库建用户并授权：

   CREATE DATABASE espocrm CHARACTER SET utf8mb4; CREATE USER 'espo'@'%' IDENTIFIED BY '<password>'; GRANT ALL PRIVILEGES ON espocrm.* TO 'espo'@'%';

3. 若用 PostgreSQL，确认php -m | grep -i pdo_pgsql有输出，没有就安装后再试
4. 检查防火墙/安全组是否放行 3306（或 5432）端口：ss -lntp | grep 3306

坑三：URL 重写不生效（404 或 URL 里带 index.php）

症状描述：站内跳转大量 404，或地址栏出现index.php?entryPoint=...这类原始路径。

原因分析：重写模块未启用，或 Nginx 缺少指向index.php的兜底规则。

解决方案：

1. Apache：a2enmod rewrite && systemctl restart apache2，并确认对应 Directory 段里有AllowOverride All
2. Nginx：确认location /里有try_files $uri $uri/ /index.php?$query_string;，改完nginx -t && systemctl reload nginx
3. 验证重写链路：curl -I http://localhost/login应返回 200 而不是 404
4. 若站点部署在子目录，检查 Web 根是否仍正确指向public/，而非误配到仓库根目录

坑四：上传附件失败或大文件传不上去

症状描述：小文件正常，超过几 MB 的附件上传报 413 或截断错误。

原因分析：upload_max_filesize、post_max_size或 Nginx 的client_max_body_size限制过小。

解决方案：

1. php -i | grep -E 'upload_max_filesize|post_max_size'看当前值
2. 修改 php.ini（官方推荐参数为 20M 起步）：

   upload_max_filesize = 20M post_max_size = 20M memory_limit = 256M max_execution_time = 180

3. Nginx 侧同步调大：client_max_body_size 50M;
4. 重启 PHP-FPM 与 Nginx 后，用curl -i -F "f=@bigfile.zip" http://crm.example.com/这类方式复测

生产级优化：性能、安全与监控三件套

上线稳定后，把这三块补齐，才算"生产级"。

性能调优：

-- MySQL / MariaDB：缓冲池给到可用内存的 50%~70% SET GLOBAL innodb_buffer_pool_size = 512M; -- PostgreSQL 对应项 ALTER SYSTEM SET shared_buffers = '256MB'; ALTER SYSTEM SET effective_cache_size = '512MB';

缓存在data/config.php中配置，把文件缓存切换为 Redis 对并发收益明显（redis驱动参数含host、port）；PHP 端memory_limit = 256M是官方推荐值，长任务（如批量导入）可适当上调。

安全加固：

1. 强制 HTTPS：申请证书并配置重定向，避免登录凭据明文传输
2. 备份双轨制：数据库 + 文件系统都要备

   mysqldump -u espo -p espocrm > backup_$(date +%Y%m%d).sql tar -czf espocrm_fs_$(date +%Y%m%d).tar.gz /var/www/espocrm/data /var/www/espocrm/custom

   ⚠ 别漏了data/（配置、缓存、附件）和custom/（你的全部自定义扩展）

3. 版本更新：关注官方发布节奏，升级前先备份、先在测试环境验证
4. 最小权限：数据库账号只授予业务库权限；data/config.php含密钥，确保 Web 用户之外的账号读不到它

监控维护清单：

• 每天检查一次data/logs/下的应用日志，关注 PHP 与数据库错误
• 定期清理过期日志与临时缓存，防止磁盘占满
• 观察计划任务队列：若作业长期堆积，先确认 cron 是否真的在跑（crontab -l）

扩展与社区：把平台用出深度

部署只是起点，EspoCRM 真正的价值在"能改"。

可扩展方向：

• 自定义实体：在custom/Espo/Modules/下新建模块，添加自己的数据模型、字段与关系
• 工作流与自动化：基于钩子（Hooks）和记录生命周期事件做业务规则，如状态变更自动通知
• API 集成：所有功能都走 REST API，对接内部系统、BI 或移动端都从这一层入手；API 行为可参考 application/Espo/Core/Api/
• 主题与界面定制：内置多个主题（Espo、Glass、Light 等），布局以 JSON 元数据描述，改布局不用改代码

社区资源：

• 使用问题、功能建议：官方社区论坛（README 中的 Community & Support 入口）
• 开发文档：官方 docs 站点的 Development 板块，后端强调依赖注入与静态类型，前端基于嵌套视图与自定义框架
• 翻译：通过 README 指向的 POEditor 项目参与多语言维护

落地最佳实践：先小范围试点（一个销售团队）→ 培训核心用户 → 用导入功能分批迁移历史数据 → 按使用反馈迭代字段和布局，比"一次上全量"稳得多。

收尾行动清单：接下来做这5件事

部署完成不是终点。按顺序勾掉下面5项，你的 CRM 才算真正跑起来：

• 配好每日 cron：php cron.php每分钟触发，保证后台作业正常流转
• 建立备份任务：数据库 +data//custom/文件双轨备份，并恢复演练一次
• 上线 HTTPS，确认 HTTP 自动 301 跳转
• 建一个非管理员测试账号，验证角色权限隔离是否符合预期
• 导入一批真实客户/商机数据，让团队在真实数据上开始试用

系统已经就绪，剩下的事很简单：把第一个客户、第一单商机录进去。30分钟的部署投入，接下来交给你的业务流程——有任何卡点，先查本指南的问答区，再去看应用日志，基本都能自助解决。

EspoCRM 安装完成后的商机管理界面：按阶段统计销售机会，底部是商机卡片列表

【免费下载链接】espocrmEspoCRM – Open Source CRM Application项目地址: https://gitcode.com/GitHub_Trending/es/espocrm