下面示例显示了如何创建一个用户宏，在这个用户宏中显示文本 'Hello World!' 和任何用户在宏内容中输入的内容。 Macro name helloworld Visibility Visible to all users in the Macro Browser Macro Title Hello World Description Displays "Hello World" and the macro body. Categories Confluence Content Icon URL 可以设置为空。 Documentation URL 可以设置为空。 Macro body processing Rendered Template 在模板字段中输入下面的内容 - 这个示例将会直接在页面中进行输出： ## @noparams Hello World! $body 如果你希望文本显示在相对的 AUI message class 的话，如下所示： ## @noparams <div class="aui-message closeable"> Hello World! $body </div> 在页面中使用 'Hello World' 宏 Now you can add the macro to your Confluence page using the Macro Browser, or by typing {hello in the editor and selecting the macro from the list of suggestions. 页面显示的结果是   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

这个页面为你在创建用户宏的最佳实践中包含了一些小技巧和建议。 为你的宏添加一个简短的描述 我们鼓励你为你的宏在 模板（Template ）添加一个备注的描述，可以参考下面的显示的内容： ## Macro title: My macro name ## Macro has a body: Y or N ## Body processing: Selected body processing option ## Output: Selected output option ## ## Developed by: My Name ## Date created: dd/mm/yyyy ## Confluence version: Version it was developed for ## Installed by: My Name ## Short description of what the macro does 在宏浏览器中展示你的参数 宏浏览器是为你用户使用配置你的宏的最简单的方式。你可以指定你的宏的分类，图标的连接定义在宏浏览器中为用户展示的信息的参数等。 为宏参数提供默认值 一般来说你不能保证用户能够完整的提供用户的参数，一个让宏进行校验是否收到了正确的参数的话，你可以在你的宏中指定参数并在后面使用。 请参考下面的示例，在这个宏中有 3 个参数，当用户不提供参数的时候，这些参数的默认值将会被使用。 #set($spacekey= $paramspacekey) #set($numthreads= $paramnumthreads) #set($numchars= $paramnumchars) ## Check for valid space key, otherwise use current #if (!$spacekey)   #set ($spacekey=$space.key) #end ## Check for valid number of threads, otherwise use default of 5 #if (!$numthreads)   #set ($numthreads=5) #end ## Check for valid excerpt size, otherwise use default of 35 #if (!$numchars)   #set ($numchars=35) #end 考虑安全提示 我们建议你为你定义的宏进行一些权限方面的测试。例如，限制页面和空间权限来避免没有权限的用户可能的不经意间的显示。请查看 Writing User Macros 页面中的内容。   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

编辑一个用户宏 希望对一个用户宏进行编辑： 进入  > 基本配置（General Configuration） > 用户宏（User Macros） 在相关的宏的边上，单击 编辑（Edit） 更新宏的详细信息 单击 保存（Save） 删除一个用户宏 希望删除一个用户宏： 进入  > 基本配置（General Configuration） > 用户宏（User Macros） 当前系统中定义的用户宏将会完全显示出来 在相关的用户宏上，单击 删除（Delete） 在删除一个用户宏之前，你应该查找使用了这个用户宏的所有页面和博客页面。如果你删除的用户宏还在页面中被引用了的话，你的用户将会在页面中看到 'unknown macro' 错误信息。   https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

如果你想创建自定义的宏的话，用户宏能够帮你完成这个任务。这个可以在你系统中应用特定的操作，比如说应用自定义格式等。 用户用是在 Confluence 创建和和管理的，你需要有一定的编码基础才可以。 你需要具有系统管理员权限来创建和应用用户自定义宏。 希望创建一个新的用户宏： 进入  > 基本配置（General Configuration） > 用户宏（User Macros） 选择 创建一个用户宏（Create a User Macro） 输入宏的一些详细信息（请查看下面列表） 单击 添加（Add） 宏名称（Macro name） 宏的名字，将会出现在代码中。 可见（Visibility） 这个选项控制谁可以在宏浏览器中查看这个宏或者自动完成功能。选项有： 所有用户可见（Visible to all users） 仅系统管理员可见（Visible only to system administrators） 请注意，如果你选择仅系统管理员可见的话，用户任然可以看到用在页面中输出的结果，宏的占位符也还是在编辑页面中出现的，这个仅仅在宏浏览器和自动完成的时候隐藏了。 所有宏的信息都是可以找到的，包括宏的标题，描述，参数名称和其他元数据。尽管宏只能被系统管理员查看到，也请不要在用户宏中定义任何敏感信和保密信息。 宏标题（Macro Title） 在宏浏览器和自动完成功能中出现的宏标题。 描述（Description） 这个描述信息将会出现在宏浏览器中。宏浏览器的查找将会对查找字段在宏标题和描述中的文字进行匹配。 分类（Categories） 为你的宏在宏浏览器中选择一个或多个分类。 图标 URL（Icon URL） 如果你希望宏浏览器为你的宏显示图标的话，输入绝对地址（例如 http://mysite.com/mypath/status.png）或相对于 Confluence base URL 的相对地址（例如：/images/icons/macrobrowser/status.png） 。 文档 URL（Documentation URL） 如果你的宏有文档的话，请在这里输入文档的 URL。 宏内容处理（Macro Body Processing） 指定 Confluence 应该如何处理你的宏的内容。 宏的内容中包含了在 Confluence 页面中如何处理的信息。如果你的宏有一个内容，所有宏的内容将会在 $body 变量字段中可用。 处理宏内容字段选项包括有： No macro body 选择这个选项，如果你的宏没有任何内容的话。 Escaped Confluence 将会添加在 HTML 标记中添加转义字符。如果你希望显示 HTML 标记在生产的页面中的时候，你可以使用转义字符。例如：如果内容为 <b>Hello World</b> 那么将会在生成页面中显示   <b>Hello World</b>。 Unrendered 内容中的 HTML 将会在模板输出之前进行处理。请确定模板中的 HTML 是非再生的。 Rendered Confluence 将会对 HTML 宏内容的部分进行让浏览器进行解析。例如宏内容为 <b>Hello World</b> 这个内容将会显示 Hello World。 模板（Template ） 这里是你写的代码去确定宏应该是什么样子的。 在宏模板中使用 HTML 和 Confluence 自定义 XML 元素。 你可以使用  Velocity 模板语言。这里是有关 Velocity project 项目的相关信息。 如果你的宏有 body 内容，你的宏可以将 body 的文本引用为 '$body'。 每个参数变量必须有一个与之对应的元数据定义。在你的宏参数中使用 @param 来定义元数据。 当使用参数传递信息，请参考 $paramXXX 在 'XXX' 的参数，是你定义 @param 元数据后来引用的参数。 如果你的宏不能接受参数，请使用 @noparams 。 请查看 Writing User Macros 要么获得更多的信息和示例。 希望使用插件完成编辑？ 如果你希望将你的自定义宏按照插件进行分发的话，请参考  User Macro plugin module 页面中的内容。如果你希望使用更加复杂，更加程序化的宏的话，你需要写成 Macro plugin 宏。 https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros

所有的组件通过 统一插件管理器（Universal Plugin Manager）进行管理，这个也被称为 UPM。UPM 可以在几乎所有的 Atlassian 应用中找到，能够提供完整同意的插件安装管理体验。希望进入统一插件管理器（UPM）页面，在 Confluence 的页面顶部，单击 > 组件（Add-ons）。 UPM  允许你进行下面的操作： 从  Atlassian Marketplace 中查找，发现和安装新的组件。 安装或者删除组件。 配置组件设置。 为组件所在的模块中，启用或者禁用组件。 在升级 Confluence 之前确定组件的兼容性。 你需要具有 Confluence 管理员权限才能访问 UPM。请访问 Request Add-ons 页面获取用户如何找到和请求组件。 请查看 Universal Plugin Manager documentation 来获得更多有关 UPM 的信息。 禁用和卸载组件 你可以从安装的组件中禁用或者取消订阅你已经不再使用的组件。请查看 Disabling and enabling add-ons 页面获得有关更多取消和启用的相关信息。 一旦组件被禁用了，这个组件相关的所有功能将马上不能使用。如果一个组件包括了宏（macros），那么使用这个宏的页面见鬼出现未知宏（unknown macro）的错误信息。为了避免这个错误，你可以在禁用这个这个组件的时候，你可以通过检查宏使用状态来检查你站点中使用的宏。 进入 > 基本配置（General Configuration）  > 宏使用（Macro Usage）。   https://www.cwiki.us/display/CONFLUENCEWIKI/Managing+Add-ons+or+Plugins

一个 组件（add-on）是与 Confluence 分开安装的功能，能够加强 Confluence 的功能和使用。插件（plugin）和 组件（add-on）这 2 个词通常是一起使用的。 一共有 2 个主要类型的组件： 系统级别的组件 - 这个类型的组件为 Confluence 系统提供核心的功能 用户安装的组件 - 这个类型的组件通常可以单独下载。在 The Marketplace 中通常由 Atlassian 开发或者第三方的公司开发。 有关在 Confluence 中开发你自己组件的方法，请参考页面 Confluence Developer documentation 中的内容。   https://www.cwiki.us/display/CONFLUENCEWIKI/Managing+Add-ons+or+Plugins

最佳实践 SAML 授权仅仅在有限的时间进行校验。你需要确定运行你的应用的计算机时间与 IdP 的时间是同步的。 如果你应用中的用户和用户组是通过用户目录进行配置的，你通常希望用户来源目录和你的 IdP 和 Atlassian 应用使用相同的 LDAP 目录。用户需要在用户目录支中存在才可以使用 SSO 进行登录。 故障排除 如果你错误的配置了 SAML 收取，或者不能登录到你的 IdP。你可以通过删除请求来让你的登录授权恢复（在你用户目录中为一个管理员用户配置使用一个用户名和密码）。 curl -u admin_user:admin_password -X DELETE http://base-url/product/rest/authconfig/1.0/saml 如果授权有错误发生，用户将只能看到基本的错误信息。基于安全的考虑，有关错误的具体信息将不会显示，你需要检查应用程序的日志来找到错误发生的具体原因和问题是什么。 在一些情况下，你可能看到你的 IdP 显示错误信息。在这种情况下，你需要一些 IdP 的诊断工具来确定你的 IdP 的问题，这方面问题的解决 Atlassian 不提供相关的服务。 当使用 使用 SAML 为主授权（Use SAML as primary authentication）同时你还有有验证码被启用的话，使用 HTTP 的基本授权（例如在 REST 资源调用）可能将用户锁定，如果用户输入的错误用户名和密码信息次数太多的话。在这种情况下，需要一个系统管理进入后台重新设置用户登录错误次数的计数。 https://www.cwiki.us/display/CONFLUENCEWIKI/SAML+SSO+for+Confluence+Data+Center

希望在 Confluence 中配置SAML： Go to  > 基本配置（General Configuration） > SAMl 授权（SAML Authentication）。 选择 SAML 单点登录（SAML single sign-on）。 配置下面的设置：   Single sign-on issuer 这个值是是由你 IdP 提供的，作为设置 SAML 的一部分。有时候这个被称为 'Entity ID' 发布者是将会接受授权请求表单的 IdP 应用。 Identity provider single sign-on URL 这个值是是由你 IdP 提供的，作为设置 SAML 的一部分 这个定义的是当登录后你用户将要重定向的 URL。 X.509 Certificate 这个值是是由你 IdP 提供的，作为设置 SAML 的一部分。有时候这个被称为 ''Signing certificate'。这个键通常以 '-----BEGIN CERTIFICATE-----' 开头。 这个含有public key，我们将用这个校验由你 IdP 发出的授权请求。 Login mode 这个定义了你的用户可以使用 SSO，通常的可选项为： 使用 SAML 为二级授权（Use SAML as secondary authentication） – 默认情况下，应用将使用资金登录表单来登录系统。你可以通过使用 SAML登录，如果到你的 IdP 然后选择你的应用的话，或者使用下面的 URL 进行登录：BASE-URL/plugins/servlet/external-login。我们推荐你使用这个方法，因为你可以用这个方法测试所有的配置，并确定用户可以使用 SSO 登录。 使用 SAML 为主授权（Use SAML as primary authentication） – 在这个模式中，所有基于浏览器的用户将会被从应用登录界面中重定向到 IdP 界面来登录系统，可能可以使用的授权如下： 基本授权（Basic Auth） 通过定义 REST 的基于表单的授权（Form-based auth via dedicated REST endpoint） 存在的记住我令牌（Existing Remember Me tokens） 你需要确定你的 SAMl 授权正确配置后才可以启用这个模式。 Remember user logins 当你选择这个的时候，登录成功的用户将会被浏览器记住。当访问其他浏览器的时候，用户将会自动进行登录而不需要使用 SAMl 进行第二次登录。 Confluence 数据中心使用 'remember me' 来启用在 2 个节点中的登录。在这个页面中将 记住用户登录（Existing Remember Me tokens）设置为禁用可以重写 Confluence 的表现同时将会提示用户在移动到另外节点中的时候 Confluence 将会要求再次登录。我们推荐设置  Remember user logins 为启用。 下面的配置信息在授权界面中提供，同时将会被要求配置你的额 IdP：   Assertion Consumer Service URL 这个是 IdP  将会返回 SAML 授权请求的地址。 Audience URL (Entity ID) 这个是 IdP  准备 SAML 授权请求的地址。 单击 保存配置（Save configuration）。 一旦你顺利完成你的应用程序和你的 IdP 配置后，你可以开始使用 SSO 了。   https://www.cwiki.us/display/CONFLUENCEWIKI/SAML+SSO+for+Confluence+Data+Center

如果你希望 Confluence 提供 SSO，将需要将 Confluence 添加到你的 IdP 中。一些后续的步骤将会与你的 IdP 有关，但是你通常需要： 在你的 IdP 中定义一个 'application' 提供你应用的一些数据，包括在你授权界面中需要的数据。 请确定你 IdP 中的 NameId 用户设置为你 Atlassian 应用的用户名 在应用中给出正确的用户权限 在设置你 IdP 过程的最后，将会提供一些配置你 Atlassian 应用需要的数据。 https://www.cwiki.us/display/CONFLUENCEWIKI/SAML+SSO+for+Confluence+Data+Center

请确定 SAML 授权是安全和私有的，你需要在你的应用程序中设置SSL/TLS。 请参考in the application. See Running Confluence Over SSL or HTTPS 页面中的内容。 一旦上面的设置完成，你需要确定你的应用程序的 configured base URL 使用的是 HTTPS 协议。 如果你在你的服务器配置上使用了反向代理（reverse proxy），请阅读下面的文章： Proxying Atlassian server applications with Apache HTTP Server (mod_proxy_http) Securing your Atlassian applications with Apache using SSL 当在反向代理中使用 SSL/TLS，你需要确定你应用服务器请求的 URL 为你的反向代理与完整的域名对应。通常这个可以在 <Connector> 目录中配置，需要配置正确的  proxyName, proxyPort, secure 和 scheme 配置。请阅读上面的文章中的具体配置实例。   https://www.cwiki.us/display/CONFLUENCEWIKI/SAML+SSO+for+Confluence+Data+Center