跳到主要内容

系统配置

OmniCRM 使用两个主要的配置系统：crm_config.yaml 用于后端 API 设置，环境变量 用于 React UI。本指南涵盖所有配置选项及其修改方法。

配置文件概述​

后端 API 配置：

  • 文件： OmniCRM-API/crm_config.yaml
  • 格式： YAML
  • 要求： 更改后需要重启 API
  • 用于： 数据库、集成、安全、配置

前端 UI 配置：

  • 文件： OmniCRM-UI/.env
  • 格式： 环境变量
  • 要求： 更改后需要重建 UI
  • 用于： 品牌、功能、外部服务

后端配置 (crm_config.yaml)​

crm_config.yaml 文件包含所有后端系统设置。

数据库配置​

database:
  username: omnitouch
  password: omnitouch2024
  server: localhost

字段：

  • username - MySQL 数据库用户名
  • password - MySQL 数据库密码
  • server - 数据库服务器主机名或 IP（默认：localhost）

数据库连接：

  • 数据库名称硬编码为 omnicrm
  • 默认端口：3306���MySQL 默认）
  • 连接字符串： mysql+pymysql://username:password@server/omnicrm

安全提示： 切勿将此文件与真实凭据一起提交到版本控制。使用特定于环境的配置或秘密管理。

服务类型​

service_types:
  - omnicharge
  - mobile
  - internet
  - iptv
  - voip

目的： 定义 service_type 字段的有效服务类型值。

默认类型：

  • mobile - 移动/蜂窝服务
  • internet - 固定互联网（光纤、DSL、无线）
  • iptv - 电视服务
  • voip - 语音通信服务
  • omnicharge - 计费/收费服务

在此处添加自定义服务类型以满足您的特定用例。

HSS (家庭用户服务器) 配置​

hss:
  hss_peers:
    - 'http://10.179.2.140:8080'
  apn_list: "1,2,3,4,5,6"

字段：

  • hss_peers - 用于用户管理的 HSS 服务器 URL 列表
  • apn_list - 逗号分隔的 APN（接入点名称）标识符列表

用于： 移动网络配置和用户身份验证。

Mailjet 邮件配置​

mailjet:
  api_key: your_mailjet_api_key
  api_secret: your_mailjet_api_secret

  api_crmCommunicationCustomerWelcome:
    from_email: "support@yourcompany.com"
    from_name: "Your Company Support"
    template_id: 5977509
    subject: "Welcome to Your Company"

  api_crmCommunicationCustomerInvoice:
    from_email: "billing@yourcompany.com"
    from_name: "Your Company Billing"
    template_id: 6759851
    subject: "Your Invoice - "

配置的邮件类型：

  • api_crmCommunicationCustomerWelcome - 新客户欢迎邮件
  • api_crmCommunicationCustomerInvoice - 发票发送
  • api_crmCommunicationCustomerInvoiceReminder - 逾期发票提醒
  • api_crmCommunicationUserWelcome - 新员工用户欢迎
  • api_crmCommunicationUserPasswordReset - 密码重置请求
  • api_crmCommunicationUserPasswordResetSuccess - 密码重置成功
  • api_crmCommunicationUserPasswordChange - 密码更改通知
  • api_crmCommunicationEmailVerification - 邮箱地址验证
  • api_crmCommunicationsBalanceExpired - 服务到期通知
  • api_crmCommunicationsBalanceLow - 余额不足警报

模板 ID：

在创建邮件模板后从您的 Mailjet 账户获取。有关详细信息，请参见 integrations_mailjet。

配置配置​

provisioning:
  failure_list: ['admin@yourcompany.com', 'ops@yourcompany.com']

字段：

  • failure_list - 在配置失败时通知的电子邮件地址

当 Ansible 剧本在配置过程中失败时，系统会将错误详细信息发送到这些地址。

发票��置​

invoice:
  template_filename: 'your_invoice_template.html'

字段：

  • template_filename - 用于发票生成的 HTML 模板文件

模板文件应存在于 OmniCRM-API/templates/ 目录中。

CRM 基础 URL​

crm:
  base_url: 'http://localhost:5000'

目的： Ansible 剧本用于向 CRM 发出 API 调用。

重要：

  • 不要包含尾部斜杠
  • 如果剧本在不同服务器上运行，请使用可公开访问的 URL
  • 部署到生产环境时更新（例如，https://api.yourcrm.com）

OCS (在线计费系统) 配置​

ocs:
  ocsApi: 'http://10.179.2.142:8080/api'
  ocsTenant: 'mnc380.mcc313.3gppnetwork.org'
  cgrates: 'localhost:2080'

字段：

  • ocsApi - OCS REST API 端点 URL
  • ocsTenant - 多租户 OCS 部署的租户标识符
  • cgrates - CGRateS JSON-RPC 端点（主机：端口）

用于： 实时计费、余额管理、使用跟踪。

SMSC (短信中心) 配置​

smsc:
  source_msisdn: 'YourCompany'
  smsc_url: 'http://10.179.2.216/SMSc/'
  api_key: 'your_smsc_api_key'

字段：

  • source_msisdn - 外发 SMS 的发送者 ID（公司名称或短代码）
  • smsc_url - 短信中心 API 端点
  • api_key - SMSC API 的身份验证密钥

用���： 发送 SMS 通知（余额警报、一次性密码等）。

小区广播配置​

cbc_url: 'http://10.179.1.113:8080'

目的： 小区广播中心（CBC）API 端点用于紧急警报。

有关使用详细信息，请参见 features_cell_broadcast。

JWT 秘密密钥​

jwt_secret: '2b93110f723db60172c8e9a1eaa80027a9a9c3f05b44e50dc3fcf38dba68d87e'

目的： 用于签署 JWT 身份验证令牌的秘密密钥。

安全性：

  • 使用以下命令生成：openssl rand -hex 32
  • 绝不要公开分享
  • 更改此密钥会使所有现有用户会话失效
  • 对于开发/暂存/生产使用不同的密钥

Stripe 支付配置​

stripe:
  secret_key: 'sk_test_...'
  publishable_key: 'pk_test_...'
  currency: 'usd'
  statement_descriptor_suffix: 'YOURCOMPANY'

字段：

  • secret_key - Stripe 秘密 API 密钥（以 sk_ 开头）
  • publishable_key - Stripe 可发布密钥（以 pk_ 开头）
  • currency - ISO 4217 货币代码（usd、gbp、aud、eur 等）
  • statement_descriptor_suffix - 出现在客户信用卡对账单上的文本

密钥类型：

  • 测试密钥：sk_test_... 和 pk_test_...（用于开发）
  • 生产密钥：sk_live_... 和 pk_live_...（用于生产）

有关���置详细信息，请参见 integrations_stripe。

API 密钥​

api_keys:
  "your-secure-api-key-minimum-32-chars":
    roles: ["admin"]
    ips: ["127.0.0.1", "::1"]
  "another-api-key-for-specific-service":
    roles: ["customer_service_agent_1"]
    ips: ["10.0.1.50"]

结构：

  • 密钥（字符串）： 实际的 API 密钥（至少 32 个字符）
  • roles（列表）： 此密钥可以访问的角色名称
  • ips（列表，可选）： 允许使用此密钥的 IP 地址

生成 API 密钥：

openssl rand -base64 48

角色：

  • admin - 对所有端点的完全访问权限
  • 在 RBAC 系统中定义的自定义角色

有关详细信息，请参见 administration_api_keys 和 concepts_api。

IP 白名单​

ip_whitelist:
  "10.179.2.142":
    roles: ["admin"]
  "192.168.1.100":
    roles: ["provisioning"]

目的： 允许特定 IP 地址在无需身份验证的情况下访问 API。

结构：

  • IP 地址（字符串）： 要列入白名单的 IPv4 地址
  • roles（列表）： 分配给来自此 IP 的请求的角色

安全警告：

  • 仅在受信任的内部网络中使用
  • 不得使用本地主机 IP（127.0.0.1、::1）
  • 对于外部访问，请使用 API 密钥
  • 考虑防火墙规则作为额外保护

前端配置 (.env)​

React UI 通过 OmniCRM-UI/.env 中的环境变量进行配置。

品牌配置​

REACT_APP_COMPANY_NAME="YourCompany"
REACT_APP_PORTAL_NAME="YourPortal"
REACT_APP_SELF_CARE_NAME="YourCare"
REACT_APP_COMPANY_TAGLINE="Your Company Slogan"

字段：

  • REACT_APP_COMPANY_NAME - 公司名称（出现在标题、电子邮件、品牌中）
  • REACT_APP_PORTAL_NAME - 管理门户名称（页面标题、导航）
  • REACT_APP_SELF_CARE_NAME - 客户门户名称
  • REACT_APP_COMPANY_TAGLINE - 营销标语（出现在登录页面）

示例：

区域配置​

REACT_APP_DEFAULT_LOCATION="London, United Kingdom"
REACT_APP_DEFAULT_COUNTRY="United Kingdom"
REACT_APP_DEFAULT_LANGUAGE="en"
REACT_APP_LOCALE="en-GB"

字段：

  • REACT_APP_DEFAULT_LOCATION - 地图和地址的默认位置
  • REACT_APP_DEFAULT_COUNTRY - 表单的默认国家
  • REACT_APP_DEFAULT_LANGUAGE - UI 语言（ar、ch、en、fr、gr、it、ru、sp）
  • REACT_APP_LOCALE - 日期/数字格式化区域设置（en-GB、en-US 等）

支持的语言：

  • ar - 阿拉伯语
  • ch - 中文
  • en - 英语（默认）
  • fr - 法语
  • gr - 希腊语
  • it - 意大利语
  • ru - 俄语
  • sp - 西班牙语

货币配置​

REACT_APP_CURRENCY_CODE="USD"
REACT_APP_CURRENCY_SYMBOL="$"

字段：

  • REACT_APP_CURRENCY_CODE - ISO 4217 货币代码
  • REACT_APP_CURRENCY_SYMBOL - 显示的符号（£、$、€ 等）

常见货币：

  • USD - $（美元）
  • GBP - £（英镑）
  • EUR - €（欧元）
  • AUD - $（澳大利亚元）
  • CAD - $（加元）

注意： 必须与 crm_config.yaml 中的 stripe.currency 匹配。

颜色主题配置​

REACT_APP_PRIMARY_COLOR=#405189
REACT_APP_SECONDARY_COLOR=#2bFFcf
REACT_APP_TERTIARY_COLOR=#1a9fbf

可用颜色：

  • REACT_APP_PRIMARY_COLOR - 主要品牌颜色（按钮、链接、高亮）
  • REACT_APP_SECONDARY_COLOR - 辅助颜色
  • REACT_APP_TERTIARY_COLOR - 额外辅助色
  • REACT_APP_SUCCESS_COLOR - 成功消息 (#28a745)
  • REACT_APP_INFO_COLOR - 信息消息 (#17a2b8)
  • REACT_APP_WARNING_COLOR - 警告 (#ffc107)
  • REACT_APP_DANGER_COLOR - 错误 (#dc3545)
  • REACT_APP_LIGHT_COLOR - 浅色背景 (#f8f9fa)
  • REACT_APP_DARK_COLOR - 深色文本 (#343a40)
  • REACT_APP_PRIMARY_DARK_COLOR - 主颜色的深色变体（用于深色模式/悬停状态）

格式： 十六进制颜色代码 (#RRGGBB)

字体配置​

REACT_APP_FONT_FAMILY=Quicksand

目的： 设置整个 UI 的主要字体系列。

重要： 所有字体均为 本地自托管，在 OmniCRM-UI 应用程序内。这意味着：

  • 不加载外部字体 - 字体与应用程序捆绑在一起
  • 适用于封闭环境 - 字体无需互联网访问即可工作
  • 离线操作 - 在隔离或受限网络环境中完全功能
  • 隐私 - 无需向 Google Fonts、Adobe Fonts 或其他 CDN 发出外部请求
  • 性能 - 无外部依赖的更快加载
  • 安全性 - 无第三方跟踪或通过字体请求的数据泄露

可用选项：

无衬线字体：

  • Inter
  • Roboto
  • Open Sans
  • Lato
  • Quicksand（默认）
  • Poppins
  • Nunito
  • Montserrat
  • Work Sans
  • Source Sans Pro
  • Raleway
  • Ubuntu
  • Josefin Sans
  • HKGrotesk

衬线字体：

  • Merriweather
  • Lora
  • Playfair Display

系统字体：

  • System - 使用本地设备字体以获得最佳性能和最小捆绑大小

默认： Quicksand

添加自定义字体​

是的，您可以添加额外的字体！ 所有字体都存储在应用程序中。

要添加新的自定义字体：

  1. 将字体文件添加到 OmniCRM-UI/src/assets/fonts/your-font-name/

    • 使用 WOFF2 格式以获得最佳压缩和浏览器支持
    • 包括多个字重（300、400、500、600、700）以获得正确的渲染
    • 文件命名：your-font-name-300.woff2、your-font-name-400.woff2 等

  2. 在 OmniCRM-UI/src/assets/scss/fonts/_google-fonts.scss 中定义 @font-face 规则

    //
    // 您的自定义字体 - 描述
    //

    @font-face {
      font-family: 'Your Font Name';
      font-style: normal;
      font-weight: 400;
      font-display: swap;
      src: url("../../fonts/your-font-name/your-font-name-400.woff2") format('woff2');
    }

    @font-face {
      font-family: 'Your Font Name';
      font-style: normal;
      font-weight: 700;
      font-display: swap;
      src: url("../../fonts/your-font-name/your-font-name-700.woff2") format('woff2');
    }

  3. 在 .env 文件中设置：

    REACT_APP_FONT_FAMILY=Your Font Name

字体粗细指南：

  • 300 - 轻（可选，用于细微标题）
  • 400 - 常规（必需，默认文本）
  • 500 - 中等（可选，强调）
  • 600 - 半粗体（可选，副标题）
  • 700 - 粗体（必需，标题和强文本）

注意： 所有字体保持自托管并可离线使用。无需外部 CDN 或互联���连接。

外部服务​

REACT_APP_GOOGLE_API_KEY=your_google_maps_api_key
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

字段：

  • REACT_APP_GOOGLE_API_KEY - Google Maps API 密钥（用于地图、地理定位）
  • REACT_APP_STRIPE_PUBLISHABLE_KEY - Stripe 可发布密钥（用于支付）

必须匹配：

REACT_APP_STRIPE_PUBLISHABLE_KEY 必须与 crm_config.yaml 中的 stripe.publishable_key 匹配。

Web 应用快速链接​

REACT_APP_WEB_APP_1_NAME="GitHub"
REACT_APP_WEB_APP_1_URL="https://github.com"
REACT_APP_WEB_APP_1_ICON_PATH="resources/webapp_icons/github.png"

目的： 在 UI 导航中配置最多 6 个快速访问的 Web 应用链接。

模式：

  • REACT_APP_WEB_APP_N_NAME - 显示名称
  • REACT_APP_WEB_APP_N_URL - 目标 URL
  • REACT_APP_WEB_APP_N_ICON_PATH - 图标文件路径（相对于 public/）

示例图标： GitHub、Xero、Monday.com、Gmail、MailJet、Slack

Grafana 集成​

REACT_APP_GRAFANA_URLS=http://grafana1.local/d/abc,http://grafana2.local/d/xyz
REACT_APP_GRAFANA_LABELS=Network Monitoring,Service Health
REACT_APP_GRAFANA_API_KEY=your_grafana_api_key

字段：

  • REACT_APP_GRAFANA_URLS - 逗号分隔的 Grafana 仪表板 URL 列表
  • REACT_APP_GRAFANA_LABELS - 逗号分隔的仪表板名称列表
  • REACT_APP_GRAFANA_API_KEY - 用于嵌入的 Grafana API 密钥

用法： 在 OmniCRM 仪表板页面嵌入 Grafana 仪表板。

支持 URL​

REACT_APP_FAQS_URL=https://support.yourcompany.com/faqs
REACT_APP_SUPPORT_URL=https://support.yourcompany.com

目的： 在 UI 中显示的外部支持资源链接。

社交登录​

REACT_APP_ALLOW_SOCIAL_LOGINS=yes

选项：

  • yes - 启用社交登录按钮（Google、Facebook 等）
  • no - 禁用社交登录

注意： 社交登录提供商必须单独配置。

充值和充值配置​

REACT_APP_TOPUP_PRICE_PER_DAY=10

目的： 设置自助服务门户中充值/充值服务的每日价格。

字段：

  • REACT_APP_TOPUP_PRICE_PER_DAY - 充值服务的每日价格（数值）

示例： 如果设置为 10 且货币为 USD，客户每天支付 $10 的服务费用。

注意： 此值必须与后端定价配置匹配。有关完整设置详细信息，请参见 features_topup_recharge。

应用配置更改​

后端 (crm_config.yaml)​

  1. 编辑 OmniCRM-API/crm_config.yaml
  2. 保存更改
  3. 重启 API 服务：
cd OmniCRM-API
sudo systemctl restart omnicrm-api
# 或
./restart_api.sh

更改在重启后立即生效。

前端 (.env)​

  1. 编辑 OmniCRM-UI/.env
  2. 保存更改
  3. 重建 UI：
cd OmniCRM-UI
npm run build
  1. 重启 UI 服务或 Web 服务器

开发模式：

在使用 npm start 进行开发时，重启开发服务器以应用更改。

配置最佳实践​

安全性​

  • 绝不要提交秘密 - 对于包含凭据的配置文件使用 .gitignore
  • 使用特定于环境的配置 - 分开开发/暂存/生产配置
  • 定期轮换秘密 - 定期更新 JWT 秘密、API 密钥
  • 限制 API 密钥权限 - 分配最小必要角色
  • 谨慎使用 IP 白名单 - 优先使用 API 密钥以提高安全性

维护​

  • 记录更改 - 保持配置修改的变更日志
  • 备份配置 - 在重大更改之前存储副本
  • 在暂存环境中测试 - 在生产部署之前验证配置更改
  • 版本控制 - 在 git 中跟踪配置模板（不包含秘密）

性能​

  • 使用本地数据库 - 避免使用远程数据库以提高性能
  • 配置缓存 - 如果可用，启用 OCS 缓存
  • 优化 Grafana - 限制嵌入的仪表板数量

品牌​

  • 匹配颜色 - 确保 UI 颜色与您的徽标相辅相成
  • 测试对比度 - 验证彩色背景上��文本可读性
  • 移动测试 - 检查移动设备上的品牌
  • 徽标位置 - 将公司徽标放置在 OmniCRM-UI/public/resources/ 中

故障排除​

更改未应用

  • 原因： 服务未重启或 UI 未重建
  • 修复： 在配置更改后重启 API/UI 服务

YAML 语法错误

  • 原因： 无效的 YAML 格式（缩进、引号等）
  • 修复： 在线验证 YAML 或使用 yamllint crm_config.yaml

数据库连接失败

  • 原因： 凭据错误或服务器无法访问
  • 修复： 验证数据库是否正在运行，凭据是否正确

Stripe 支付无法工作

  • 原因： 后端和前端之间的密钥不匹配
  • 修复： 确保两个文件中的 publishable_key 匹配

邮件未发送

  • 原因： 无效的 Mailjet 凭据或模板 ID
  • 修复： 验证 Mailjet API 密钥/秘密，检查模板 ID 是否存在

相关文档​

  • administration_api_keys - API 密钥管理
  • integrations_stripe - Stripe 支付设置
  • integrations_mailjet - 邮件集成
  • concepts_api - API 身份验证
  • rbac - 基于角色的访问控制