本指南适用于V20上的安装。如果你在V18上运行,请遵循此指南。
通过 setupconfig.xml 部署 3CX 和配置设置
介绍
通过创建预填充的 XML 文件来启动并自动配置 3CX。只需将 3CX 命令行工具询问您的问题的答案输入到 XML 中,并将文件存储在计算机或 cloud-init 中。 3CX 会自动解析它并自动配置您的 PBX。还可以在安装过程中包含分机、SIP 中继和 DID。
概述
“setupconfig.xml”的部署过程通过将放置在计算机上的 XML 文件来在安装过程中自动配置 3CX:
- 下载此示例安装模板XML文件。
- 手动修改 XML 文件中的配置并填写所有必需的详细信息。
- 将 setupconfig.xml 文件放置在计算机上:
- 对于 Linux,位于:“/etc/3cxpbx/setupconfig.xml”。
- 对于 Windows,位于:“C:\ProgramData\3CX\Data\setupconfig.xml”。
- 安装3CX。安装 3CX 后,命令行向导会检查上述位置是否有 XML 文件,如果找到,它会自动处理它们。
💡 提示:除了复制文件,您还可以使用 cloud-init,复制XML的内容并将其粘贴到“Advanced” / “User data”部分。考虑以下 Amazon AWS cloud-init 示例。
Cloud-init 示例
要在 cloud-init 中包含“setupconfig.xml”,请下载并使用此 cloud-init 样本:
#!/bin/bash -e mkdir -p /etc/3cxpbx cat > /etc/3cxpbx/setupconfig.xml << "<EOF>" <?xml version="1.0" encoding="utf-8"?> <!--PUT CONTENTS OF SETUPCONFIG.XML HERE--> <EOF> apt-get update dpkg-query -W -f='${Status}' sudo 2>/dev/null | grep -qF "ok installed" || apt-get -y install sudo dpkg-query -W -f='${Status}' wget 2>/dev/null | grep -qF "ok installed" || apt-get -y install wget dpkg-query -W -f='${Status}' gnupg2 2>/dev/null | grep -qF "ok installed" || apt-get -y install gnupg2 wget -O- https://repo.3cx.com/key.pub | gpg --dearmor | sudo tee /usr/share/keyrings/3cx-archive-keyring.gpg > /dev/null echo "deb [arch=$(dpkg --print-architecture) by-hash=yes signed-by=/usr/share/keyrings/3cx-archive-keyring.gpg] http://repo.3cx.com/3cx bookworm main" | sudo tee /etc/apt/sources.list.d/3cxpbx.list apt-get update apt-get -y install nginx rm -f /etc/nginx/sites-enabled/default systemctl reload nginx apt-get -y install 3cxpbx
Setupconfig.xml 解释
“setupconfig.xml”分为以下部分:
- <tcxinit> - PBX 配置工具初始阶段的参数,例如许可证、备份文件路径、网络设置、公网 IP、FQDN(3CX FQDN 或自定义 FQDN)、主机名、本地 DNS、HTTP(S) 端口、分机长度、邮件服务器、时区、国家/地区和许可证信息。
- <extensions> - 在此部分中添加要创建的分机。
- <siptrunk> - 定义要部署的 SIP 中继和 DID,并在 <inboundrules> 中添加子节点,以创建与该 SIP 中继的 DID 关联的呼入路由。
- <OutboundRules> - 添加要在此部分中创建的呼出规则。
配置向导
这是一个示例 XML 子集,对应于首次配置向导中提出的问题:
<option> <code>NumberOfExtensions</code> <answer>3</answer> </option> <option> <code>MailServerType</code> <answer>3CX</answer> </option> <option> <code>MailServerAddress</code> <answer>smtp.example.com</answer> </option> <option> <code>MailServerReplyTo</code> <answer>[email protected]</answer> </option> <option> <code>MailServerUserName</code> <answer>username</answer> </option> <option> <code>MailServerPassword</code> <answer>password</answer> </option> <option> <code>MailServerEnableSslTls</code> <answer>yes</answer> </option> <option> <code>Continent</code> <answer>North America</answer> </option> <option> <code>Country</code> <answer>United States</answer> </option> <option> <code>Timezone</code> <answer>9</answer> </option> <option> <code>OperatorVoicemail</code> <answer>999</answer> </option> <option> <code>Promptset</code> <answer>English</answer> </option> <option> <code>LicenseContactName</code> <answer>John L. Doe</answer> </option> <option> <code>LicenseCompanyName</code> <answer>My Company Ltd.</answer> </option> <option> <code>LicenseEmail</code> <answer>[email protected]</answer> </option> <option> <code>LicensePhone</code> <answer>+357 99 87654321</answer> </option> <option> <code>ResellerId</code><answer></answer> </option>
要填充“国家/地区”和“时区”,请参阅此文件并从相应列中选择值。例如,要根据列表指定“中国”,您可以使用以下配置:
<option> <code>Country</code> <answer>China</answer> </option> <option> <code>Timezone</code> <answer>+8</answer> </option>
添加分机、SIP 中继、DID 和呼出规则
使用“<extensions>”部分可以:
- 将分机名、SIP中继、呼入和呼出规则添加到设置配置文件中。
- 通过使用适当的信息配置相关 XML 节点,将 IP 电话配置到分机支持的 IP 电话的可用编解码器值和电话模板指导。
例如,要配置 Snom 720 电话,请在以下位置找到该型号: 指南 并记下相应支持的编解码器和模板文件名,即“snom.ph.xml”。在“setupconfig.xml”文件中相应的 XML 标签中输入此信息。
创建分机
要自动创建和配置新分机,请在“<extensions>”部分下的“<extension>”节点中添加信息:
<extension> <Number>000</Number> <FirstName>John</FirstName> <LastName>Smith</LastName> <EmailAddress>[email protected]</EmailAddress> <MobileNumber>801123456</MobileNumber> <OutboundCallerId>801123456</OutboundCallerId> <AuthPassword>extensionPassword</AuthPassword> <AuthID>000</AuthID> <AllowLanOnly>false</AllowLanOnly> <RecordCalls>false</RecordCalls> <TemplateFilename>snom.ph.xml</TemplateFilename> <ProvisioningFilename2>Snom 720</ProvisioningFilename2> <MAC>121212ABABAB</MAC> <Codecs> <codec>G711u</codec> <codec>G711a</codec> <codec>G722</codec> <codec>G729</codec> </Codecs> <Language>English</Language> <ProvisionType>LocalLan</ProvisionType> <AllowOwnRecordings>false</AllowOwnRecordings> </extension>
创建 SIP 中继、DID 和呼入规则
要自动创建 SIP 中继及其 DID 和呼入规则,请根据以下 XML 示例摘录,在“<siptrunk>”节点中添加相关信息:
<siptrunk> <Name>Voip Trunk 1</Name> <TemplateFilename>GenericSIPTrunk.pv.xml</TemplateFilename> <Host>trunk.example.com</Host> <Port>5050</Port> <ProxyHost>proxy.trunk.example.com</ProxyHost> <ProxyPort>5160</ProxyPort> <SimultaneousCalls>10</SimultaneousCalls> <RequireRegistrationFor>InOutCalls</RequireRegistrationFor> <AuthID>369456456456</AuthID> <AuthPassword>sgh88DMVU6Uz60MQzwvF</AuthPassword> <Use3WayAuth>true</Use3WayAuth> <SeparateAuthPassword>3WayPass</SeparateAuthPassword> <ExternalNumber>0044870478519100</ExternalNumber> <OfficeHoursDestinationType>Extension</OfficeHoursDestinationType> <OfficeHoursDestination>100</OfficeHoursDestination> <OutOfOfficeHoursDestinationType>Extension</OutOfOfficeHoursDestinationType> <OutOfOfficeHoursDestination>100</OutOfOfficeHoursDestination> <DIDNumbers>0044870478519101,0044870478519102</DIDNumbers> <OutboundCallerID>0044870478519100</OutboundCallerID> <Direction>Both</Direction> <DeliverAudio>true</DeliverAudio> <DisableVideoCalls>true</DisableVideoCalls> <SupportReinvite>false</SupportReinvite> <SupportReplaces>false</SupportReplaces> <PublicIpInSipViaHeader>1.2.3.4</PublicIpInSipViaHeader> <EnableSRTP>false</EnableSRTP> <TimeBetweenReg>120</TimeBetweenReg> <IPInRegistrationContact>Default</IPInRegistrationContact> <SpecifiedIPForRegistrationContact></SpecifiedIPForRegistrationContact> <AlternativeProxy></AlternativeProxy> <TransportProtocol></TransportProtocol> <IPMode></IPMode> <Codecs> <codec>PCMU</codec> <codec>GSM</codec> <codec>iLBC</codec> <codec>G722</codec> <codec>opus</codec> <codec>G729</codec> <codec>PCMA</codec> <codec>Speex</codec> </Codecs> <InboundRules> <InboundRule> <Name>IncomingCall1</Name> <DID>0044870478519101</DID> <OfficeHoursDestinationType>Extension</OfficeHoursDestinationType> <OfficeHoursDestination>101</OfficeHoursDestination> <OutOfOfficeHoursDestinationType>Extension</OutOfOfficeHoursDestinationType> <OutOfOfficeHoursDestination>101</OutOfOfficeHoursDestination> </InboundRule> </InboundRules> </siptrunk>
使用备份路由创建呼出规则
在“<OutboundRules>”部分,您可以添加“<OutoundRule>”节点,通过setupconfig.xml自动创建呼出规则和备份路由:
<OutboundRules> <OutboundRule> <Name>Outbound Rule 1</Name> <Prefix>111</Prefix> <DNRanges> <DNRange> <To>000</To> <From>000</From> </DNRange> <DNRange> <To>100</To> <From>105</From> </DNRange> </DNRanges> <NumberLengthRanges>9,10,11</NumberLengthRanges> <DNGroups> <Group>Sales</Group> <Group>CEO</Group> </DNGroups> <OutboundRoutes> <OutboundRoute> <Gateway>GatewayIn</Gateway> <StripDigits>0</StripDigits> <Prepend>807</Prepend> </OutboundRoute> <OutboundRoute> <Gateway>Trunk1a</Gateway> <StripDigits>1</StripDigits> <Prepend>801</Prepend> </OutboundRoute> </OutboundRoutes> </OutboundRule> </OutboundRules>
导入 SSL 证书
要在“setupconfig.xml”中包含 SSL 证书信息,请使用以下示例配置与 SSL 相关的部分:
📄 注意:不同类型的证书需要配置不同的XML节点。虽然“CertificatePath”在所有情况下都使用,但“CertificatePassword”仅用于pfx。
全新安装与恢复备份
要创建全新的 3CX 安装,只需设置 InstallationType=new 并提供您的许可证密钥,如下所示。
<tcxinit> <option> <code>InstallationType</code> <answer>new</answer> </option> <option> <code>LicenseKey</code> <answer>0000-1111-3333-4444</answer> </option> </tcxinit>
如果您想通过 setupconfig.xml 恢复现有备份,请设置 InstallationType=restore 并在 BackupFile 代码中提供备份文件的路径。
注:可以是本机实际的物理路径,也可以是http链接。如果您的备份已加密,请在 BackupPassword 代码的答案中输入备份密码。
<tcxinit> <option> <code>InstallationType</code> <answer>restore</answer> </option> <option> <code>LicenseKey</code> <answer>0000-1111-3333-4444</answer> </option> <option> <code>BackupFile</code> <answer>/var/tmp/mybackup.zip</answer> </option> <option> <code>BackupPassword</code> <answer>a0Jdtz9Jea0Dj3jk</answer> </option> </tcxinit>
设置系统所有者和凭据
配置 xml 时,您需要提供系统的分机列表。您配置的第一个分机将被分配系统所有者角色。
<extensions> <extension> <Number>100</Number> <FirstName>John</FirstName> <LastName>Smith</LastName> <EmailAddress>[email protected]</EmailAddress> ... <CustomParameters> <CustomParameter> <Name>SERVICES_ACCESS_HASH</Name> <Value>AAAAAMAnCQAQAAAAAQ92DLZ6nqkahROS…KHRMtydHb8BsLA==</Value> <ParameterType>String</ParameterType> <Create>true</Create> </CustomParameter> </CustomParameters> </extension> <extension> <Number>101</Number> <FirstName>Joanne</FirstName> <LastName>Davis</LastName> <EmailAddress>[email protected]</EmailAddress> ... </extension> ... <extensions>
配置 PBX 端口
在以下字段中指定 PBX 将用于 https、http、sip 和 3CX tunnel 的端口。
<tcxinit> <option> <code>HttpsPort</code> <answer>443</answer> </option> <option> <code>HttpPort</code> <answer>80</answer> </option> <option> <code>SipPort</code> <answer>5060</answer> </option> <option> <code>TunnelPort</code> <answer>5090</answer> </option> … </tcxinit>
设置您的邮件服务器
要将 PBX 配置为使用 3CX SMTP 服务器发送电子邮件,请在 xml 中设置以下代码:
<tcxinit> <option> <code>MailServerType</code> <answer>3CX</answer> </option> </tcxinit>
如果您想将 PBX 配置为使用您自己的 SMTP 服务器,您可以在 setupconfig.xml 中使用以下代码。
您可以从这里找到一些流行邮件提供商的 SMTP 设置。
请参考本指南有关如何使用 gmail 作为 SMTP 服务器的更多信息。
<tcxinit> <option> <code>MailServerType</code> <answer>Custom</answer> </option> <option> <code>MailServerAddress</code> <answer>my-smtp.example.com</answer> </option> <option> <code>MailServerReplyTo</code> <answer>my-email.example.com</answer> </option> <option> <code>MailServerUserName</code> <answer>mySMTPUsername</answer> </option> <option> <code>MailServerPassword</code> <answer>mySMTPPassword</answer> </option> <option> <code>MailServerEnableSslTls</code> <answer>yes/no</answer> </option> </tcxinit>
公网IP配置
以下代码控制 PBX 的公网 IP 的配置。公网 IP 代码可以设置为“自动”,以便 PBX 自动检测您的公网 IP;如果您想手动配置 PBX 的公网 IP,则可以将公网 IP 代码设置为“手动”。
如果您选择“手动”,则必须使用您的 PBX 公网 IP 填充 ManualPublicIP 代码,如下所示,否则跳过此代码。对于 StaticOrDynamicIP,代码必须设置为“静态”或“动态”。
如果您从提供商那里获得了永远不会改变的静态 IP 地址,则设置为“静态”。
否则设置为“动态”,以便 PBX 定期检查 IP 更改并相应调整配置和 DNS 记录。
<tcxinit> <option> <code>PublicIP</code> <answer>auto/manual</answer> </option> <option> <code>ManualPublicIP</code> <answer>X.X.X>X</answer> </option> <option> <code>StaticOrDynamicIP</code> <answer>static/dynamic</answer> </option> </tcxinit>
本地IP配置
以下代码控制 PBX 使用的本地接口/IP 的配置。本地 IP 代码可以设置为“自动”或“手动”。
如果设置为“自动”,PBX 将自动获取计算机网络堆栈上的第一个 IP。请注意,如果您的计算机不在 NAT 之后,则将采用公网 IP。
如果您的机器有多个网卡。适配器,您可以将 LocalIP 设置为“手动”,并使用您希望 PBX 使用的本地 IP 地址填充 ManualLocalIP 代码。
否则跳过此代码。
<tcxinit> <option> <code>LocalIP</code> <answer>auto/manual</answer> </option> <option> <code>ManualLocalIP</code> <answer>192.168.0.10</answer> </option> </tcxinit>
使用 3CX FQDN
要将 PBX 配置为使用 3CX FQDN,您需要在 setupconfig.xml 中使用以下代码。将 NeedFqdn 设置为“yes”以允许 PBX 创建您选择的 3CX FQDN、证书和 DNS 记录。仅当您计划使用自己的自定义 FQDN(需要上传自己的自定义证书并管理自己的 DNS 记录)时,才设置为“否”。
主机名必须使用您的 FQDN 的首选主机名进行填充。例如,它可以是您的公司名称。如果您将 NeedFqdn 设置为“no”,则应跳过此步骤 DomainGroup 且 DnsSuffix 控制用于 FQDN 的域名。
例如,以下配置将使用 contoso.3cx.eu 作为 FQDN 安装 PBX。
<tcxinit> <option> <code>NeedFqdn</code> <answer>yes/no</answer> </option> <option> <code>Hostname</code> <answer>contoso</answer> </option> <option> <code>DomainGroup</code> <answer>Europe</answer> </option> <option> <code>DnsSuffix</code> <answer>eu</answer> </option> </tcxinit>
可用的“域组”:非洲、亚洲、城市、大陆、欧洲、大洋洲、其他、南美洲、美国。
可以找到创建 3CX FQDN 时可使用的每个域组的所有可用后缀的列表 这里。
配置不同的本地 FQDN
默认情况下,PBX以拆分DNS模式安装,如果网络配置正确,3CX FQDN必须在局域网内外完全可解析。这意味着您自己的 DNS 服务器或防火墙应该能够执行 hairpin nat。
如果您有托管DNS,还可以选择配置不同的本地FQDN供本地各方使用。
为此,您需要将 HasLocalDns 代码设置为 “yes” ,将 InternalFqdn 代码设置为本地内部FQDN
<tcxinit> <option> <code>HasLocalDns</code> <answer>yes</answer> </option> <option> <code>InternalFqdn</code> <answer>PBX_FQDN</answer> </option> </tcxinit>
设置 PBX 语言、国家/地区、时区和提示音设置
语言代码控制 PBX 的语言(用于欢迎电子邮件、报告等)。
提示音集代码控制要在语音邮件菜单、IVR、队列等中使用的提示音集。
国家/地区代码用于允许呼叫您所在的国家/地区并用于 E164 格式。时区代码控制 PBX 使用的时区。
<tcxinit> <option> <code>Language</code> <answer>UK</answer> </option> <option> <code>Promptset</code> <answer>English</answer> </option> <option> <code>Country</code> <answer>United States</answer> </option> <option> <code>Timezone</code> <answer>9</answer> </option> </tcxinit>
PBX 可使用的语言如下:
- EN = 英语(美国)
- 英国=英语(英国)
- DE = 德语
- FR = 法语
- ES = 西班牙语
- IT = 意大利语
- PT = 葡萄牙语
- RU = 俄语
- PL = 波兰语
- ZH = 中文
这里可以找到可以使用的可用提示音集
这里可以找到可以使用的可用国家和时区代码
IP白名单/黑名单
您可以在 setupconfig.xml 中使用以下示例将单个 IP 或一系列 IP/子网列入白名单/黑名单。
请注意,<IpBlackList> 的父元素是 <SetupConfig>
您可以使用 Mask 声明单个 IP 地址 (255.255.255.255) 或声明整个子网(例如 255.255.0.0)。
将允许设置为“true”可将 IP 地址列入白名单,或设置为“false”可将其列入黑名单
<SetupConfig> <IpBlackList> <IpBlackListEntry> <Address>1.2.3.4</Address> <Mask>255.255.255.255</Mask> <Allowed>true</Allowed> <Description>Single IP Allowed</Description> </IpBlackListEntry> <IpBlackListEntry> <Address>1.2.0.0</Address> <Mask>255.255.0.0</Mask> <Allowed>false</Allowed> <Description>Range of IPs Denied</Description> </IpBlackListEntry> </IpBlackList> </SetupConfig>
配置呼出呼叫的国家/地区
您可以在 setupconfig.xml 中使用 NOTALLOWED_COUNTRYCODES 自定义参数来指定 PBX 应允许或不允许向哪些国家/地区进行呼出呼叫。
请注意,<CustomParameters> 的父元素是<SetupConfig>
<CustomParameters> <CustomParameter> <Name>NOTALLOWED_COUNTRYCODES</Name> <Value></Value> <ParameterType>String</ParameterType> <Description>Specifies the country codes which are not allowed for outbound calls</Description> <Create>true</Create> </CustomParameter> </CustomParameters>
请注意,上面 xml 中的值包含不允许的国家/地区的代码。因此,在上面的示例中,<value> 为空,所有国家/地区将允许呼出呼叫。
在某些情况下,仅允许拨出特定国家/地区的电话更为有用。在这种情况下,可以使用以下示例,其中包括所有可用的国家/地区代码。只需确保仅删除您实际希望允许呼出呼叫的国家/地区的代码。
<CustomParameters> <CustomParameter> <Name>NOTALLOWED_COUNTRYCODES</Name> <Value>001,001264,001268,001242,001246,001441,001345,00506,0053,001767,001809,001829,001849,00503,00299,001473,001671,00502,00509,00504,001876,001658,0052,001664,00505,001670,00507,001787,001939,001869,001758,001784,001868,001649,001284,001340,001721,0054,00297,00501,00591,0055,0056,0057,00593,00500,00594,00590,00592,00596,00595,0051,00508,00597,00598,0058,005993,005994,005995,005996,005997,005998,005999,00355,00376,00374,0043,00375,0032,00387,00359,00385,00357,00420,0045,00372,00298,00358,0033,0049,00350,0030,00441481,0036,00354,00353,00441624,0039,00441534,00371,00423,00370,00352,00389,00356,00373,00377,00382,0031,0047,0048,00351,0040,00378,00381,00383,00421,00386,0034,004779,0046,0041,0090,0090392,00380,0044,003906698,00971,0093,00994,00973,00880,00975,00673,00855,0086,00670,00995,00852,0091,0062,0098,00964,00972,0081,00962,00965,00996,00856,00961,00853,0060,00960,00976,0095,00977,00850,00968,0092,00970,0063,00974,007,00966,0065,0082,0094,00963,00886,00992,0066,00993,00998,0084,00967,00213,00244,00247,00229,00267,00246,00226,00257,00237,00238,00236,00235,00269,00242,00243,00225,00253,0020,00240,00291,00251,00241,00220,00233,00224,00245,00254,00266,00231,00218,00261,00265,00223,00222,00230,00262269,00269639,00212,00258,00264,00227,00234,00262,00250,00290,00239,00221,00248,00232,00252,0027,00211,00249,00268,00255,00228,002908,00216,00256,00260,0025524,00263,001684,0061,006189162,00682,00679,00689,00686,00692,00691,00674,00687,0064,00683,00672,00680,00675,00872,00685,00677,00690,00676,00688,00699,00678,00681,00870,00871,00873,00874,00875,00876,00877,00878,00879,00881,00882,00883,00979,00800,00808,00888,00991,00999,+1,+1264,+1268,+1242,+1246,+1441,+1345,+506,+53,+1767,+1809,+1829,+1849,+503,+299,+1473,+1671,+502,+509,+504,+1876,+1658,+52,+1664,+505,+1670,+507,+1787,+1939,+1869,+1758,+1784,+1868,+1649,+1284,+1340,+1721,+54,+297,+501,+591,+55,+56,+57,+593,+500,+594,+590,+592,+596,+595,+51,+508,+597,+598,+58,+5993,+5994,+5995,+5996,+5997,+5998,+5999,+355,+376,+374,+43,+375,+32,+387,+359,+385,+357,+420,+45,+372,+298,+358,+33,+49,+350,+30,+441481,+36,+354,+353,+441624,+39,+441534,+371,+423,+370,+352,+389,+356,+373,+377,+382,+31,+47,+48,+351,+40,+378,+381,+383,+421,+386,+34,+4779,+46,+41,+90,+90392,+380,+44,+3906698,+971,+93,+994,+973,+880,+975,+673,+855,+86,+670,+995,+852,+91,+62,+98,+964,+972,+81,+962,+965,+996,+856,+961,+853,+60,+960,+976,+95,+977,+850,+968,+92,+970,+63,+974,+7,+966,+65,+82,+94,+963,+886,+992,+66,+993,+998,+84,+967,+213,+244,+247,+229,+267,+246,+226,+257,+237,+238,+236,+235,+269,+242,+243,+225,+253,+20,+240,+291,+251,+241,+220,+233,+224,+245,+254,+266,+231,+218,+261,+265,+223,+222,+230,+262269,+269639,+212,+258,+264,+227,+234,+262,+250,+290,+239,+221,+248,+232,+252,+27,+211,+249,+268,+255,+228,+2908,+216,+256,+260,+25524,+263,+1684,+61,+6189162,+682,+679,+689,+686,+692,+691,+674,+687,+64,+683,+672,+680,+675,+872,+685,+677,+690,+676,+688,+699,+678,+681,+870,+871,+873,+874,+875,+876,+877,+878,+879,+881,+882,+883,+979,+800,+808,+888,+991,+999</Value> <ParameterType>String</ParameterType> <Description>Specifies the country codes which are not allowed for outbound calls</Description> <Create>true</Create> </CustomParameter> </CustomParameters>
另请参阅
最后更新
本文档最后更新于 2024 年 4 月 26 日