vectorim/element-web

Element

Element（前身为Vector和Riot）是一个基于https://github.com/matrix-org/matrix-react-sdk%E6%9E%84%E5%BB%BA%E7%9A%84Matrix Web客户端。

支持的环境

Element对不同环境有多个支持层级：

• 支持

  • 定义：问题积极分类，回归问题阻止发布
  • 桌面操作系统上Chrome、Firefox、Safari和Edge的最新2个主要版本
  • 桌面操作系统上官方Element Desktop应用的最新版本
  • 桌面操作系统指macOS、Windows和Linux版本，这些系统需得到操作系统供应商的积极支持并接收安全更新

• 实验性

  • 定义：问题被接受，回归问题不阻止发布
  • 通过当前稳定版Chrome、Firefox和Safari安装的Element PWA
  • Android、iOS和iPadOS上当前稳定版Chrome、Firefox和Safari的移动Web版本

• 不支持

  • 定义：仅影响不支持环境的问题将被关闭
  • 其他所有情况

对于在Android或iOS设备上访问Element，我们目前推荐原生应用https://github.com/vector-im/element-android%E5%92%8Chttps://github.com/vector-im/element-ios%E3%80%82

快速开始

测试Element最简单的方法是使用托管版本：<[]>。对于喜欢体验最新功能的用户，develop分支会持续部署到<[]>。

要托管自己的Element副本，最快的方法是使用预构建的Element发布版本：

1. 从https://github.com/vector-im/element-web/releases下载最新版本
2. 在Web服务器上解压缩tarball
3. 将element-x.x.x目录移动（或符号链接）到适当的名称
4. 在Web服务器中配置正确的缓存头（见下文）
5. 通过复制config.sample.json到config.json并修改来配置应用。详情参见配置文档。
6. 在浏览器中输入URL并登录Element！

发布版本使用gpg和OpenPGP标准签名，可以通过位于<[***]>的公钥进行验证。

注意，为了聊天安全，您需要通过HTTPS提供Element服务。主流浏览器也不允许通过HTTP使用VoIP/视频聊天，因为WebRTC只能通过HTTPS使用。使用localhost时存在一些例外，这被视为安全上下文，因此被允许。

要将Element安装为桌面应用，请参见下面的作为桌面应用运行。

重要安全说明

独立域名

我们不建议从与Matrix homeserver相同的域名运行Element。原因是如果有人导致Element加载和呈现来自Matrix API的***用户生成内容，可能会发生XSS（跨站脚本）漏洞，从而获得对Element（或其他应用）的受信任访问。

我们已经采取了一些粗略的缓解措施来防止这种情况，但首先不这样做仍然是良好的实践。详见https://github.com/vector-im/element-web/issues/1977。

配置最佳实践

除非有特殊要求，否则在托管Element Web时，您需要在Web服务器配置中添加以下内容：

• X-Frame-Options: SAMEORIGIN头，防止Element Web被嵌入框架并防止[点击劫持][owasp-clickjacking]
• frame-ancestors 'none'指令到Content-Security-Policy头，作为X-Frame-Options的现代替代品（尽管两者都应包含，因为并非所有浏览器都支持）
• X-Content-Type-Options: nosniff头，[禁用MIME嗅探][mime-sniffing]
• X-XSS-Protection: 1; mode=block;头，用于旧版浏览器的基本XSS保护

如果使用nginx，配置如下：

add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "frame-ancestors 'none'";

注意：如果您已在其他地方设置了Content-Security-Policy头，应修改它以包含frame-ancestors指令，而不是添加最后一行。

Docker部署方案

Docker镜像可用于作为Web服务器提供element-web服务。使用预构建镜像的最简单方法：

bash
docker run -p 80:80 vectorim/element-web

要提供自定义config.json，将卷映射到/app/config.json。例如，如果自定义配置位于/etc/element-web/config.json，则Docker命令为：

bash
docker run -p 80:80 -v /etc/element-web/config.json:/app/config.json vectorim/element-web

要自己构建镜像：

bash
git clone https://github.com/vector-im/element-web.git element-web
cd element-web
git checkout master
docker build .

如果要构建自定义分支或使用develop分支，请检出适当的element-web分支，然后运行：

bash
docker build -t \
    --build-arg USE_CUSTOM_SDKS=true \
    --build-arg REACT_SDK_REPO="https://github.com/matrix-org/matrix-react-sdk.git" \
    --build-arg REACT_SDK_BRANCH="develop" \
    --build-arg JS_SDK_REPO="https://github.com/matrix-org/matrix-js-sdk.git" \
    --build-arg JS_SDK_BRANCH="develop" \
    .

从源代码构建

Element是使用现代ES6构建的模块化Web应用，并使用Node.js构建系统。确保安装了最新的LTS版本Node.js。

推荐使用yarn而不是npm。如果尚未安装yarn，请参阅Yarn安装指南。

1. 安装或更新node.js，确保node版本至少为当前推荐的LTS版本。
2. 如果尚未安装yarn，请先安装。
3. 克隆仓库：git clone https://github.com/vector-im/element-web.git。
4. 切换到element-web目录：cd element-web。
5. 安装依赖项：yarn install。
6. 通过复制config.sample.json到config.json并修改来配置应用。详见配置文档。
7. 运行yarn dist构建要部署的tarball。解压缩此文件将得到一个特定版本的目录，其中包含需要放在Web服务器上的所有文件。

注意：Windows不支持yarn dist，因此Windows用户可以运行yarn build，这将把所有必要文件构建到webapp目录中。如果不使用dist脚本，Element的版本将不会显示在设置中。然后可以将webapp目录挂载到Web服务器上以实际提供应用服务，这完全是静态内容。

作为桌面应用运行

Element也可以作为桌面应用运行，由Electron包装。您可以从<[***]>下载预构建版本，或者如果您愿意，也可以自己构建。

要自己构建，请按照https://github.com/vector-im/element-desktop上的说明进行操作。

非常感谢@aviraldg为Electron集成所做的初始工作。

作为桌面应用运行的其他选项：

• @asdf:matrix.org指出可以使用nativefier，它可以正常工作：

bash
yarn global add nativefier
nativefier https://app.element.io/

配置文档展示了如何根据需要覆盖桌面应用的默认设置。

在Kubernetes中运行

提供的element-web docker镜像也可以在Kubernetes集群中运行。有关更多详细信息，请参阅Kubernetes示例。

config.json

Element支持各种设置来配置默认服务器、行为、主题等。详见配置文档。

Labs功能

Element的某些功能可以通过设置中Labs部分的标志启用。其中一些功能在https://github.com/vector-im/element-web/blob/develop/docs/labs.md%E4%B8%AD%E6%9C%89%E6%8F%8F%E8%BF%B0%E3%80%82

缓存要求

当您从自己的Web服务器提供Element服务时，Element要求以下URL不被缓存：

/config.*.json
/i18n
/home
/sites
/index.html

我们还建议您通过将Web服务器配置为对/返回Cache-Control: no-cache，强制浏览器在页面加载时重新验证Element的任何缓存副本。这确保浏览器在部署后下次页面加载时获取Element的新版本。请注意，这已在我们Dockerfile的nginx配置中为您配置。

开发环境设置

Element的大部分功能实际上在matrix-react-sdk和matrix-js-sdk模块中。可以通过某种方式设置这些模块，使其易于跟踪git中的develop分支，并能够进行本地更改而无需每次手动重建。

首先克隆并构建matrix-js-sdk：

bash
git clone https://github.com/matrix-org/matrix-js-sdk.git
pushd matrix-js-sdk
yarn link
yarn install
popd

然后以类似方式处理matrix-react-sdk：

bash
git clone https://github.com/matrix-org/matrix-react-sdk.git
pushd matrix-react-sdk
yarn link
yarn link matrix-js-sdk
yarn install
popd

克隆仓库并切换到element-web目录：

bash
git clone https://github.com/vector-im/element-web.git
cd element-web

通过复制config.sample.json到config.json并修改来配置应用。详见配置文档。

最后，构建并启动Element：

bash
yarn link matrix-js-sdk
yarn link matrix-react-sdk
yarn install
yarn start

等待几秒钟，初始构建完成后，您将看到类似以下内容：

[element-js] <s> [webpack.Progress] 100%
[element-js]
[element-js] ℹ ｢wdm｣:    1840 modules
[element-js] ℹ ｢wdm｣: Compiled successfully.

请记住，该命令不会终止，因为它运行Web服务器并在源文件更改时重建。此开发服务器还禁用了缓存，因此不要在生产环境中使用它。

在浏览器中打开<[***]>，即可看到您新构建的Element。

运行测试

tests目录中有许多应用级测试；这些测试旨在与Jest和JSDOM一起运行。要运行它们：

yarn test

端到端测试

有关如何运行端到端测试，请参见https://github.com/matrix-org/matrix-react-sdk/#end-to-end-tests%E3%80%82

翻译

要添加新翻译，请参阅翻译文档。

开发指南，请参见翻译开发文档。