1. 项目概述为什么你需要深入了解Axure Cloud的配置文件如果你正在使用Axure Cloud进行原型设计的在线协作与托管无论是团队内部使用还是对外交付那么迟早有一天你会遇到需要调整其行为的时候。比如你想把默认的HTTP访问改成更安全的HTTPS或者想把默认的英文界面改成中文又或者你需要把它部署到公司内网的服务器上实现私有化部署。这时候一个名为customsettings.json的文件就成了你手中的“万能钥匙”。这个文件就是Axure Cloud的配置文件。它不像我们常见的那些有图形界面的设置面板而是一个需要你手动创建和编辑的纯文本JSON文件。很多用户甚至是一些已经用了一段时间Axure Cloud的团队对这个文件的存在和威力都知之甚少。大家往往习惯于在Web管理界面里点点鼠标一旦遇到界面里解决不了的问题比如深度定制、安全加固或私有化部署中的特殊需求就感到束手无策。我经历过好几次因为没配置好这个文件导致部署后访问异常、邮件发送失败或者团队成员权限混乱的情况。踩过这些坑之后我才真正意识到customsettings.json不是高级玩家的玩具而是保障Axure Cloud稳定、安全、符合企业规范运行的基石。它直接决定了你的Axure Cloud实例“长什么样”以及“怎么工作”。本文将带你彻底拆解这个配置文件从它的作用、结构到每一个关键参数的含义和配置方法并结合私有部署、HTTPS等实际场景让你不仅能看懂更能用得好。2. 配置文件的核心customsettings.json的定位与创建Axure Cloud的配置文件其官方名称就是customsettings.json。这个文件并非在安装包里预先存在而是需要你在部署Axure Cloud Server私有部署版本后在特定的目录下手动创建的。它的核心定位是“覆盖和扩展默认配置”。Axure Cloud Server在启动时会先加载一套内置的默认配置。这套默认配置能满足最基本的运行需求比如使用内置的H2数据库、运行在8080端口、使用HTTP协议等。然后系统会去查找customsettings.json文件。如果找到了就会用这个文件里的设置去覆盖掉对应的默认值。如果没找到就全部使用默认配置。这种机制非常灵活你只需要在配置文件中声明你想要修改的那部分设置即可其他未声明的部分继续保持默认。2.1 文件应该放在哪里文件的位置取决于你的操作系统和安装方式。对于最常见的基于Windows的安装包部署Windows (安装包部署) 文件应放置在C:\Program Files\Axure\Axure Cloud Server目录下。这是Axure Cloud Server的主安装目录。Windows (Docker部署) 如果你使用Docker通常需要通过卷挂载Volume Mount的方式将宿主机上的customsettings.json文件映射到容器内的/opt/axure/axure-cloud-server/目录。这是容器内的默认应用目录。Linux/macOS 对于基于Java包.jar的部署你需要将customsettings.json文件放在与axure-cloud-server.jar可执行文件相同的目录下。一个简单的验证方法是启动Axure Cloud服务后查看其日志文件。在最初的几行日志里通常会打印出它正在加载的配置路径你可以从中确认它是否成功读取了你的customsettings.json。2.2 文件的基本结构与JSON语法customsettings.json是一个标准的JSON文件。JSONJavaScript Object Notation是一种轻量级的数据交换格式采用“键值对”的结构易于人阅读和编写也易于机器解析和生成。文件的基本骨架如下{ “设置项分组1”: { “参数A”: “值A”, “参数B”: “值B” }, “设置项分组2”: { “参数C”: 100, “参数D”: true } }花括号{} 表示一个JSON对象整个配置文件就是一个大对象。键Key 带引号的字符串如“server”“smtp”。它表示一个配置分组或具体参数名。值Value 可以是字符串如“https://axure.your-company.com”、数字如8080、布尔值true或false、数组[]或另一个嵌套的对象{}。逗号, 用于分隔同一层级内的不同键值对但最后一个键值对后面不能有逗号这是JSON语法的一个常见错误点。注意JSON文件对格式要求严格。编辑时建议使用专业的代码编辑器如VS Code、Notepad、Sublime Text它们通常有JSON语法高亮和格式验证功能能帮你避免因缺少引号、逗号或括号不匹配导致的解析错误。一个格式错误的JSON文件会导致Axure Cloud Server启动失败或忽略整个配置文件。3. 逐项解析customsettings.json的关键配置项理解了文件的基本结构后我们来深入看看里面到底能配置些什么。我会按照从外到内、从基础到高级的顺序结合实际场景来解释每个重要配置项。3.1 服务器与网络配置 (server)这是最基础也是最重要的配置组决定了你的Axure Cloud如何被访问。{ “server”: { “host”: “axure.your-company.com”, “port”: 443, “contextPath”: “/axure”, “secure”: true, “proxy”: { “scheme”: “https”, “host”: “axure.your-company.com”, “port”: 443 } } }host: 服务器的主机名或IP地址。在私有部署中这里通常填写你服务器的内网IP如192.168.1.100或域名如axure.internal.com。如果部署在公网则填写你的公网域名。注意这个值会影响到系统生成的链接如分享链接、邮件中的链接所以必须配置正确。port: Axure Cloud Server内部服务监听的端口。默认是8080。当你使用HTTP直接访问时URL就是http://host:8080。但在生产环境我们几乎从不直接暴露这个端口。contextPath: 应用的上下文路径。如果你希望Axure Cloud不是部署在网站根目录/而是像http://your-domain.com/axure这样访问就需要设置“contextPath”: “/axure”。这在你一个服务器上部署了多个应用时很有用。secure: 布尔值设置为true时系统会认为所有请求都是通过HTTPS发起的。这个设置通常需要和反向代理配合使用。proxy: 这是配置中的重中之重尤其是在配置HTTPS时。绝大多数情况下我们不会让Axure Cloud Server直接处理HTTPS而是在它前面部署一个反向代理服务器如Nginx, Apache。proxy配置就是告诉Axure Cloud“真正的用户是通过前面的代理服务器访问你的代理服务器的协议、主机和端口是这些。”scheme: 代理服务器使用的协议设为“https”。host: 用户实际访问的域名如“axure.your-company.com”。port: 代理服务器监听的端口HTTPS通常是443。为什么需要proxy配置因为当Nginx代理以HTTPS接收用户请求后会以HTTP协议或HTTPS但通常是HTTP以减轻后端压力转发给后端的Axure Cloud Server运行在8080端口。此时Axure Cloud Server收到的请求头如X-Forwarded-Proto,Host来自Nginx。如果不配置proxyAxure Cloud会错误地认为请求来自http://localhost:8080从而导致它生成的任何重定向链接或URL都是错误的HTTP链接。配置了proxy后Axure Cloud就能正确识别原始请求的协议和主机生成正确的HTTPS链接。3.2 数据库配置 (database)Axure Cloud默认使用内嵌的H2数据库这对于演示或极小规模使用没问题但绝不适用于生产环境。H2是文件型数据库性能、稳定性和并发能力都很有限。生产环境必须切换到如MySQL、PostgreSQL这类专业数据库。{ “database”: { “type”: “mysql”, “host”: “localhost”, “port”: 3306, “name”: “axure_cloud”, “username”: “axure_user”, “password”: “YourStrongPassword123!”, “parameters”: “?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneUTC” } }type: 数据库类型。支持“mysql”和“postgresql”。根据你的数据库选择填写。host/port: 数据库服务器的地址和端口。name: 要使用的数据库名。你需要提前在MySQL或PostgreSQL中创建好这个空数据库。Axure Cloud在首次启动时会自动创建所需的表结构。username/password: 连接数据库的账号密码。请确保该账号拥有对该数据库的足够权限通常是所有权限。parameters: JDBC连接参数。这是一个非常重要的部分经常被忽略导致连接失败。对于MySQL常见的参数包括useUnicodetruecharacterEncodingutf8: 确保正确处理中文等非英文字符。useSSLfalse: 如果数据库和应用在同一内网且未配置SSL证书可以设为false。生产环境建议启用SSL并配置为true。serverTimezoneUTC: 设置会话时区避免时间错误。可以按需设置为Asia/Shanghai等。实操心得切换数据库前务必先备份H2数据库的数据如果已有。Axure Cloud官方通常不提供从H2到MySQL的自动迁移工具你需要手动导出导入或者干脆将其视为一次全新的安装让团队成员重新上传原型。对于全新部署强烈建议一开始就配置好外部数据库。3.3 邮件服务器配置 (smtp)Axure Cloud的很多协作功能依赖邮件例如新用户注册邀请、密码重置通知、项目评论提醒等。如果不配置SMTP这些功能将静默失败用户体验很差管理员也会收不到任何通知。{ “smtp”: { “host”: “smtp.office365.com”, “port”: 587, “username”: “noreplyyour-company.com”, “password”: “YourEmailPassword”, “fromAddress”: “noreplyyour-company.com”, “fromName”: “Axure Cloud Team”, “starttls”: true, “auth”: true } }host/port: 你的企业邮箱SMTP服务器地址和端口。常见的有腾讯企业邮smtp.exmail.qq.com(SSL端口465 TLS端口587)阿里企业邮smtp.mxhichina.com(端口465或587)Office 365:smtp.office365.com(端口587)Gmail:smtp.gmail.com(端口587)username/password: 用于发送邮件的邮箱账号和密码或授权码。强烈建议使用专门的“通知邮箱”或“无回复邮箱”而不是个人邮箱。fromAddress/fromName: 发件人地址和名称收件人看到的邮件来源。starttls/auth: 安全连接和认证开关。对于使用587端口的TLS连接starttls通常设为true。auth也必须为true。踩坑记录我遇到过最常见的问题是端口和加密方式不匹配。比如服务器要求用SSL端口465但配置里却用了starttls: true适用于TLS/端口587。另一个坑是密码用了邮箱的登录密码而有些邮箱如Gmail、163需要的是生成的“授权码”。配置完成后一定要在Axure Cloud的管理员设置里测试发送一封邮件这是验证配置是否生效的最直接方法。3.4 高级与安全配置这部分配置关系到系统的安全性、定制化程度和运维便利性。3.4.1 安全与存储 (security,storage){ “security”: { “allowedOrigins”: [“https://your-company.com”], “sessionTimeout”: 7200 }, “storage”: { “type”: “file”, “directory”: “D:/axure-cloud-data” } }security.allowedOrigins: 配置CORS跨域资源共享允许的来源。如果你需要将Axure Cloud嵌入到其他内部系统如公司门户的iframe中或者有前端应用需要调用其API就必须在这里添加前端的域名否则浏览器会因同源策略而阻止请求。这是一个重要的安全配置不要轻易设为[“*”]允许所有。security.sessionTimeout: 用户会话超时时间单位是秒。默认是7200秒2小时。可以根据安全策略调整。storage: 定义原型文件、上传的附件等数据的存储方式。默认是“file”即存储在服务器本地磁盘的某个目录下。directory: 指定存储路径。务必将其设置到一个空间充足、并且做了定期备份的磁盘分区。不要使用安装目录或系统盘避免系统升级或重装时数据丢失。3.4.2 本地化与定制 (localization)Axure Cloud Server支持多语言界面通过配置可以强制使用某种语言或设置默认语言。{ “localization”: { “defaultLocale”: “zh_CN”, “forceDefaultLocale”: false } }defaultLocale: 设置默认语言。例如“zh_CN”表示简体中文“en”表示英文。用户首次访问时如果浏览器语言不匹配或未设置将使用此默认语言。forceDefaultLocale: 如果设为true将强制所有用户使用defaultLocale设置的语言忽略浏览器语言偏好。这对于统一企业内部使用环境很有用。3.4.3 日志配置 (logging)生产环境排查问题离不开日志。你可以调整日志的详细程度和输出位置。{ “logging”: { “level”: “INFO”, “file”: “/var/log/axure-cloud/axure.log”, “maxFileSize”: “10MB”, “maxHistory”: 10 } }level: 日志级别从详细到简洁依次为TRACE,DEBUG,INFO,WARN,ERROR。生产环境通常用INFO或WARN排查问题时可以临时改为DEBUG。file: 指定日志文件路径而不是仅输出到控制台。便于长期保存和查看。maxFileSize/maxHistory: 日志文件滚动策略。单个文件最大10MB最多保留10个历史文件避免日志占满磁盘。4. 实战场景私有部署与HTTPS配置全流程了解了各个配置项后我们通过一个最典型的实战场景——在企业内网私有化部署Axure Cloud并启用HTTPS——来串联所有配置。假设我们有一台CentOS 7服务器内网IP为192.168.10.50我们希望通过域名axure.internal.com已在内部DNS解析进行HTTPS访问。4.1 场景分析与架构设计我们的目标架构是用户通过浏览器访问https://axure.internal.com- Nginx反向代理处理SSL证书- Axure Cloud Server运行在8080端口HTTP协议。这样做的好处是安全由Nginx专业处理SSL/TLS加密和解密。性能Nginx可以处理静态文件、负载均衡等减轻后端压力。灵活可以在Nginx层面做访问控制、限流、日志记录等。因此我们的customsettings.json需要正确反映这个架构特别是server.proxy部分。4.2 准备SSL证书对于内网环境我们可以使用自签名证书或者由内部CA颁发的证书。这里以自签名证书为例生产环境建议使用内部CA证书。在服务器上使用OpenSSL生成证书仅示例实际请根据安全规范操作# 生成私钥 openssl genrsa -out axure.key 2048 # 生成证书签名请求 (CSR) openssl req -new -key axure.key -out axure.csr -subj “/CNaxure.internal.com” # 生成自签名证书 openssl x509 -req -days 365 -in axure.csr -signkey axure.key -out axure.crt将生成的axure.crt证书和axure.key私钥文件放在一个安全目录例如/etc/nginx/ssl/。4.3 配置Nginx反向代理创建或修改Nginx的站点配置文件例如/etc/nginx/conf.d/axure.confserver { listen 443 ssl http2; server_name axure.internal.com; # SSL证书路径 ssl_certificate /etc/nginx/ssl/axure.crt; ssl_certificate_key /etc/nginx/ssl/axure.key; # SSL优化配置可选但推荐 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; # 反向代理到Axure Cloud location / { proxy_pass http://localhost:8080; # 指向Axure Cloud Server proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 传递原始协议https proxy_set_header X-Forwarded-Host $host; # 传递原始主机名 proxy_set_header X-Forwarded-Port $server_port; # 传递原始端口 # 以下两行对于WebSocket支持很重要Axure Cloud的实时协作功能需要 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection “upgrade”; } # 静态文件缓存可选提升性能 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { proxy_pass http://localhost:8080; expires 30d; add_header Cache-Control “public, immutable”; } } # 可选将HTTP请求重定向到HTTPS server { listen 80; server_name axure.internal.com; return 301 https://$server_name$request_uri; }配置完成后运行nginx -t测试配置语法无误后systemctl reload nginx重载配置。4.4 编写完整的customsettings.json现在我们来编写放在Axure Cloud Server应用目录下的customsettings.json文件。这个文件需要告诉Axure Cloud“你运行在8080端口但用户是通过https://axure.internal.com:443访问你的。”{ “server”: { “host”: “192.168.10.50”, // 服务器内网IP用于内部通信识别 “port”: 8080, // 内部服务端口 “secure”: true, // 因为Nginx传过来的是https协议头 “proxy”: { “scheme”: “https”, “host”: “axure.internal.com”, // 用户实际访问的域名 “port”: 443 } }, “database”: { “type”: “mysql”, “host”: “localhost”, “port”: 3306, “name”: “axure_cloud_prod”, “username”: “axure_user”, “password”: “SecureDBPassw0rd!”, “parameters”: “?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai” }, “smtp”: { “host”: “smtp.exmail.qq.com”, “port”: 465, “username”: “noreplyyour-company.com”, “password”: “YourSMTPAuthCode”, “fromAddress”: “noreplyyour-company.com”, “fromName”: “公司Axure云平台”, “starttls”: false, // 端口465使用SSL不是STARTTLS “auth”: true }, “security”: { “allowedOrigins”: [“https://your-company-portal.com”] // 如果不需要嵌入其他系统可以暂时不配或留空数组 }, “storage”: { “type”: “file”, “directory”: “/data/axure-cloud/storage” // 指向一个独立的数据盘 }, “localization”: { “defaultLocale”: “zh_CN” }, “logging”: { “level”: “INFO”, “file”: “/data/axure-cloud/logs/axure-cloud.log” } }4.5 部署、启动与验证放置配置文件将上述customsettings.json文件上传到Axure Cloud Server的安装目录例如/opt/axure/axure-cloud-server/。启动服务启动Axure Cloud Server服务。对于Windows服务可以在服务管理器中启动对于Linux的JAR包使用java -jar axure-cloud-server.jar命令。查看日志立即查看应用日志如配置的/data/axure-cloud/logs/axure-cloud.log或控制台输出确认没有报错并且日志中出现了类似“Loaded custom settings from [file path]”的信息说明配置文件已成功加载。验证访问在浏览器中输入https://axure.internal.com。你应该能看到Axure Cloud的登录/注册页面并且浏览器地址栏显示为安全的HTTPS可能因自签名证书会有安全警告点击高级继续访问即可。验证功能创建一个新用户检查是否收到邀请邮件验证SMTP。上传一个RP文件检查是否能正常预览和分享验证存储和代理配置。在另一个浏览器中登录尝试协作评论功能验证WebSocket通过代理是否正常。5. 故障排查与日常维护指南即使配置看起来完美实际运行中也可能遇到问题。以下是一些常见故障的排查思路和日常维护建议。5.1 配置文件未生效症状修改了customsettings.json后重启服务但设置似乎没变。排查检查文件位置和权限确认文件是否放在了正确的目录并且运行Axure Cloud服务的用户如www-data,axure有读取该文件的权限。检查JSON语法一个多余的逗号、缺少的引号或括号都会导致整个文件被忽略。使用在线JSON校验工具或编辑器的lint功能检查。查看启动日志这是最直接的证据。在服务启动的最初几秒日志里寻找关于加载自定义配置的信息。如果没找到相关日志很可能文件没被读到。检查配置项名称确认你使用的配置项键名Key完全正确大小写敏感。参考官方文档核对。5.2 HTTPS访问异常出现重定向循环或链接错误症状能打开首页但登录后跳转到HTTP链接或者浏览器提示“重定向次数过多”。排查首要检查server.proxy配置99%的问题出在这里。确认scheme,host,port与用户实际访问的URL完全一致。如果用户用域名访问这里必须是域名不能是IP。检查Nginx配置确认proxy_set_header X-Forwarded-Proto $scheme;这一行已正确配置并且Nginx确实接收的是HTTPS请求$scheme变量值为https。检查server.secure当配置了正确的proxy时secure应设置为true。检查防火墙确保服务器的443端口Nginx和8080端口Axure在防火墙中是放行的。5.3 数据库连接失败症状服务启动失败日志报错Communications link failure或Access denied for user。排查验证数据库可连通在Axure服务器上使用命令行工具如mysql -h host -u user -p尝试连接数据库排除网络和基础认证问题。检查数据库权限确保配置文件中指定的用户有权限从Axure服务器IP地址访问指定的数据库并且拥有CREATE、INSERT、SELECT等所有必要权限。检查连接参数重点关注parameters字符串。时区serverTimezone和SSL设置useSSL是常见坑点。如果数据库强制要求SSL而你没配置证书却设置了useSSLtrue就会失败。检查数据库版本确保你的Axure Cloud Server版本支持你所用的MySQL/PostgreSQL版本。过新或过旧的数据库版本可能导致兼容性问题。5.4 邮件功能不工作症状用户收不到邀请邮件、密码重置邮件。排查检查SMTP日志Axure的日志级别调到DEBUG然后触发一个发邮件动作如邀请用户查看详细的SMTP通信日志。通常会明确显示连接失败、认证失败等具体原因。端口与加密方式这是最易错点。465端口通常对应SSLstarttls: false587端口通常对应STARTTLSstarttls: true。务必与企业邮件服务商文档核对。密码/授权码确认使用的是否是SMTP专用密码或授权码而非邮箱登录密码。发件人地址有些邮件服务器要求fromAddress必须与username一致。网络策略检查服务器是否有出网限制是否允许连接到外部SMTP服务器的特定端口。5.5 日常维护建议配置文件版本管理将customsettings.json纳入你的版本控制系统如Git。任何修改都有迹可循便于回滚和团队协作。敏感信息分离不要在customsettings.json中明文写入数据库密码、SMTP密码。可以考虑将这些敏感信息提取为环境变量在配置文件中引用如“password”: “${DB_PASSWORD}”。具体实现方式需参考Axure Cloud的文档或通过启动脚本注入环境变量。定期备份备份两个关键部分一是customsettings.json配置文件本身二是storage.directory指定的数据目录那里存放着所有上传的原型文件。日志监控将应用日志接入公司的日志监控系统如ELK Stack便于集中分析和设置告警。升级前测试在升级Axure Cloud Server版本前务必在测试环境用相同的customsettings.json进行验证。新版本可能会废弃某些旧参数或引入新参数。经过这样一番从原理到实战的梳理customsettings.json这个文件对你来说应该不再神秘。它就像Axure Cloud Server的“中枢神经”通过精细地调整它你可以让这套系统完美地融入到你公司的IT基础设施和安全体系中。记住每次修改后细心查看日志多做功能验证这些时间投入远比出了问题后再去排查要划算得多。