Skip to content

Commit cd85a9f

Browse files
SoulterSoulter
committed
docs: add mattermost docs
1 parent 66e06e3 commit cd85a9f

9 files changed

Lines changed: 321 additions & 1 deletion

File tree

‎astrbot/core/config/default.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -506,7 +506,7 @@ class ChatProviderTemplate(TypedDict):
506506
"satori_heartbeat_interval": 10,
507507
"satori_reconnect_delay": 5,
508508
},
509-
"kook": {
509+
"KOOK": {
510510
"id": "kook",
511511
"type": "kook",
512512
"enable": False,

‎dashboard/src/assets/images/platform_logos/mattermost.svg‎

Lines changed: 2 additions & 0 deletions
Loading

‎dashboard/src/i18n/locales/en-US/features/config-metadata.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -556,6 +556,18 @@
556556
"description": "Bot Token",
557557
"hint": "If you are in mainland China, set a proxy or change api_base in Other Settings."
558558
},
559+
"mattermost_url": {
560+
"description": "Mattermost URL",
561+
"hint": "Mattermost service URL, for example https://chat.example.com."
562+
},
563+
"mattermost_bot_token": {
564+
"description": "Mattermost Bot Token",
565+
"hint": "The access token generated after creating a bot account in Mattermost."
566+
},
567+
"mattermost_reconnect_delay": {
568+
"description": "Mattermost Reconnect Delay",
569+
"hint": "Delay in seconds before reconnecting after the WebSocket disconnects. Defaults to 5 seconds."
570+
},
559571
"type": {
560572
"description": "Adapter Type"
561573
},

‎dashboard/src/i18n/locales/ru-RU/features/config-metadata.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -552,6 +552,18 @@
552552
"description": "Токен бота",
553553
"hint": "Если вы находитесь в материковом Китае, установите прокси или измените api_base в разделе «Другие настройки»."
554554
},
555+
"mattermost_url": {
556+
"description": "URL Mattermost",
557+
"hint": "Адрес сервиса Mattermost, например https://chat.example.com."
558+
},
559+
"mattermost_bot_token": {
560+
"description": "Bot Token Mattermost",
561+
"hint": "Токен доступа, созданный после добавления bot-аккаунта в Mattermost."
562+
},
563+
"mattermost_reconnect_delay": {
564+
"description": "Задержка переподключения Mattermost",
565+
"hint": "Сколько секунд ждать перед переподключением после разрыва WebSocket. По умолчанию 5 секунд."
566+
},
555567
"type": {
556568
"description": "Тип адаптера"
557569
},

‎dashboard/src/i18n/locales/zh-CN/features/config-metadata.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -558,6 +558,18 @@
558558
"description": "Bot Token",
559559
"hint": "如果你的网络环境为中国大陆，请在 `其他配置` 处设置代理或更改 api_base。"
560560
},
561+
"mattermost_url": {
562+
"description": "Mattermost URL",
563+
"hint": "Mattermost 服务地址，例如 https://chat.example.com。"
564+
},
565+
"mattermost_bot_token": {
566+
"description": "Mattermost Bot Token",
567+
"hint": "在 Mattermost 中创建 Bot 账户后生成的访问令牌。"
568+
},
569+
"mattermost_reconnect_delay": {
570+
"description": "Mattermost 重连延迟",
571+
"hint": "WebSocket 断开后的重连等待时间，单位为秒。默认 5 秒。"
572+
},
561573
"type": {
562574
"description": "适配器类型"
563575
},

‎dashboard/src/utils/platformUtils.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ export function getPlatformIcon(name) {
4040
return new URL('@/assets/images/platform_logos/line.png', import.meta.url).href
4141
} else if (name === 'matrix') {
4242
return new URL('@/assets/images/platform_logos/matrix.svg', import.meta.url).href
43+
} else if (name === 'mattermost') {
44+
return new URL('@/assets/images/platform_logos/mattermost.svg', import.meta.url).href
4345
}
4446
}
4547

‎docs/.vitepress/config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ export default defineConfig({
9898
{ text: "Telegram", link: "/telegram" },
9999
{ text: "LINE", link: "/line" },
100100
{ text: "Slack", link: "/slack" },
101+
{ text: "Mattermost", link: "/mattermost" },
101102
{ text: "Misskey", link: "/misskey" },
102103
{ text: "Discord", link: "/discord" },
103104
{ text: "KOOK", link: "/kook" },
@@ -336,6 +337,7 @@ export default defineConfig({
336337
{ text: "Telegram", link: "/telegram" },
337338
{ text: "LINE", link: "/line" },
338339
{ text: "Slack", link: "/slack" },
340+
{ text: "Mattermost", link: "/mattermost" },
339341
{ text: "Misskey", link: "/misskey" },
340342
{ text: "Discord", link: "/discord" },
341343
{

‎docs/en/platform/mattermost.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Connecting to Mattermost
2+
3+
The Mattermost adapter connects to your Mattermost server through a Bot Token and WebSocket. After finishing the two parts below, AstrBot can send and receive messages in Mattermost channels and direct messages.
4+
5+
## Create the AstrBot Mattermost Platform Adapter
6+
7+
Go to the `Bots` page, click `+ Create Bot`, and choose `Mattermost`.
8+
9+
On the configuration page, enable it first, then fill in:
10+
11+
- `Mattermost URL`: your Mattermost server URL, for example `https://chat.example.com`
12+
- `Mattermost Bot Token`: the access token generated after creating a bot account in Mattermost
13+
- `Mattermost Reconnect Delay`: how long AstrBot waits before reconnecting after a WebSocket disconnect, default `5`
14+
15+
Then click save.
16+
17+
## Deploy Mattermost
18+
19+
If you do not have a Mattermost server yet, use the official Mattermost Docker Compose repository:
20+
21+
- Official docs: https://docs.mattermost.com/deployment-guide/server/containers/install-docker.html
22+
- Official repository: https://github.com/mattermost/docker
23+
24+
The current quick-start flow recommended by Mattermost is:
25+
26+
```bash
27+
git clone https://github.com/mattermost/docker
28+
cd docker
29+
cp env.example .env
30+
```
31+
32+
Then update at least these values in `.env`:
33+
34+
- `DOMAIN`
35+
- `MATTERMOST_IMAGE_TAG`
36+
- It is also recommended to set `MM_SUPPORTSETTINGS_SUPPORTEMAIL`
37+
38+
Create the data directories and set ownership:
39+
40+
```bash
41+
mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
42+
sudo chown -R 2000:2000 ./volumes/app/mattermost
43+
```
44+
45+
Choose one startup mode:
46+
47+
Without the bundled NGINX:
48+
49+
```bash
50+
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d
51+
```
52+
53+
With the bundled NGINX:
54+
55+
```bash
56+
docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
57+
```
58+
59+
Access URLs:
60+
61+
- Without NGINX: `http://your-domain:8065`
62+
- With NGINX: `https://your-domain`
63+
64+
> [!TIP]
65+
> Mattermost currently states that production Docker support is Linux-only. macOS and Windows are better suited for development or testing.
66+
67+
## Create a Bot in Mattermost
68+
69+
### 1. Enable Bot Account Creation
70+
71+
Open the Mattermost system console:
72+
73+
`System Console > Integrations > Bot Accounts`
74+
75+
Enable `Enable Bot Account Creation`.
76+
77+
### 2. Create the Bot Account
78+
79+
Go to:
80+
81+
`Product menu > Integrations > Bot Accounts`
82+
83+
Click `Add Bot Account` and fill in:
84+
85+
- `Username`
86+
- `Display Name`
87+
- `Description`
88+
89+
After creation, copy the generated Bot Token. It is shown only once. Paste it into AstrBot's `Mattermost Bot Token` field.
90+
91+
### 3. Add the Bot to a Channel
92+
93+
Add the bot to the channel where AstrBot should work. Otherwise the bot will not be able to properly receive and send messages in that channel.
94+
95+
## How to Fill in Mattermost URL
96+
97+
`Mattermost URL` should be the external URL of your Mattermost server, without a trailing slash. For example:
98+
99+
```text
100+
https://chat.example.com
101+
```
102+
103+
If you are only testing locally, you can also use:
104+
105+
```text
106+
http://127.0.0.1:8065
107+
```
108+
109+
If both AstrBot and Mattermost run in containers, prefer an address reachable from the AstrBot container, such as the Mattermost service name on the same Docker network.
110+
111+
## Start and Verify
112+
113+
After saving the AstrBot platform adapter configuration:
114+
115+
1. Make sure the AstrBot logs do not show Mattermost authentication or WebSocket connection errors.
116+
2. Send a message in a channel that includes the bot, or send the bot a direct message.
117+
3. If AstrBot replies normally, the integration is working.
118+
119+
## Common Issues
120+
121+
### Invalid Token Errors
122+
123+
Usually one of these:
124+
125+
- You copied a user token instead of the bot token
126+
- The token contains extra spaces
127+
- The bot account was deleted or the token was regenerated
128+
129+
### Connected but No Channel Messages Arrive
130+
131+
Check these first:
132+
133+
- The bot has been added to the target channel
134+
- `Mattermost URL` points to an address AstrBot can actually reach
135+
- Your Mattermost reverse proxy forwards WebSocket traffic correctly
136+
137+
### Mattermost Opens in Browser but AstrBot Still Cannot Connect
138+
139+
If AstrBot runs in a container while `Mattermost URL` is set to `localhost` or `127.0.0.1`, AstrBot will connect to itself instead of the Mattermost service. In that case, switch to an address reachable inside the Docker network.

‎docs/zh/platform/mattermost.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# 接入 Mattermost
2+
3+
Mattermost 适配器通过 Bot Token 和 WebSocket 连接到 Mattermost 服务器。完成下面两部分配置后，AstrBot 就可以在 Mattermost 频道和私聊中收发消息。
4+
5+
## 创建 AstrBot Mattermost 平台适配器
6+
7+
进入 `机器人` 页面，点击 `+ 创建机器人`，选择 `Mattermost`。
8+
9+
在配置页中先打开 `启用`，然后填写以下字段：
10+
11+
- `Mattermost URL`：你的 Mattermost 服务地址，例如 `https://chat.example.com`
12+
- `Mattermost Bot Token`：在 Mattermost 中创建 Bot 账户后生成的访问令牌
13+
- `Mattermost 重连延迟`：WebSocket 断开后的重连等待时间，默认 `5`
14+
15+
填写完成后点击保存。
16+
17+
## 部署 Mattermost
18+
19+
如果你还没有 Mattermost 服务，建议直接使用 Mattermost 官方提供的 Docker Compose 仓库：
20+
21+
- 官方文档：https://docs.mattermost.com/deployment-guide/server/containers/install-docker.html
22+
- 官方仓库：https://github.com/mattermost/docker
23+
24+
官方当前推荐的快速部署步骤如下：
25+
26+
```bash
27+
git clone https://github.com/mattermost/docker
28+
cd docker
29+
cp env.example .env
30+
```
31+
32+
然后至少修改 `.env` 中的：
33+
34+
- `DOMAIN`
35+
- `MATTERMOST_IMAGE_TAG`
36+
- 建议补充 `MM_SUPPORTSETTINGS_SUPPORTEMAIL`
37+
38+
接着创建数据目录并设置权限：
39+
40+
```bash
41+
mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
42+
sudo chown -R 2000:2000 ./volumes/app/mattermost
43+
```
44+
45+
启动方式二选一：
46+
47+
不使用内置 NGINX：
48+
49+
```bash
50+
docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d
51+
```
52+
53+
使用内置 NGINX：
54+
55+
```bash
56+
docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
57+
```
58+
59+
访问地址：
60+
61+
- 不使用 NGINX：`http://你的域名:8065`
62+
- 使用 NGINX：`https://你的域名`
63+
64+
> [!TIP]
65+
> Mattermost 官方当前说明中，Docker 生产支持仅限 Linux。macOS 和 Windows 更适合开发或测试用途。
66+
67+
## 在 Mattermost 中创建 Bot
68+
69+
### 1. 开启 Bot 账户创建
70+
71+
进入 Mattermost 的系统控制台：
72+
73+
`System Console > Integrations > Bot Accounts`
74+
75+
开启 `Enable Bot Account Creation`。
76+
77+
### 2. 创建 Bot 账户
78+
79+
进入：
80+
81+
`Product menu(左上角的图标) > Integrations > Bot Accounts`
82+
83+
点击 `Add Bot Account`，填写：
84+
85+
- `Username`
86+
- `Display Name`
87+
- `Description`
88+
89+
创建完成后复制生成的 Bot Token。这个 Token 只会展示一次，随后填写到 AstrBot 的 `Mattermost Bot Token` 中。
90+
91+
### 3. 将 Bot 加入频道
92+
93+
把刚创建的 Bot 添加到你准备让 AstrBot 工作的频道中，否则机器人无法在该频道正常收发消息。
94+
95+
## Mattermost URL 如何填写
96+
97+
`Mattermost URL` 填 Mattermost 的外部访问地址，不要带结尾斜杠。例如：
98+
99+
```text
100+
https://chat.example.com
101+
```
102+
103+
如果你当前只是在本机测试，也可以填写：
104+
105+
```text
106+
http://127.0.0.1:8065
107+
```
108+
109+
如果 AstrBot 和 Mattermost 都在 Docker 中运行，请优先填写 AstrBot 容器可访问到的地址，例如同一 Docker 网络中的服务名地址。
110+
111+
## 启动并验证
112+
113+
保存 AstrBot 平台适配器配置后：
114+
115+
1. 确保 AstrBot 日志中没有出现 Mattermost 认证失败或 WebSocket 连接失败。
116+
2. 在 Mattermost 中向 Bot 所在频道发送消息，或直接给 Bot 发私聊。
117+
3. 如果 AstrBot 正常回复，说明接入成功。
118+
119+
## 常见问题
120+
121+
### 提示 Token 无效
122+
123+
通常是以下原因：
124+
125+
- 复制的不是 Bot Token
126+
- Token 复制时带了空格
127+
- Bot 账户被删除或重新生成了 Token
128+
129+
### 连接成功但收不到频道消息
130+
131+
优先检查：
132+
133+
- Bot 是否已经加入目标频道
134+
- Mattermost URL 是否填写为 AstrBot 实际可访问的地址
135+
- Mattermost 反向代理是否正确转发了 WebSocket 请求
136+
137+
### 本机部署能打开页面，但 AstrBot 连接不到
138+
139+
如果 AstrBot 运行在容器里，而 Mattermost URL 填的是 `localhost` 或 `127.0.0.1`，那么 AstrBot 实际连接到的是它自己的容器，而不是 Mattermost。此时应改为 Docker 网络内可访问的地址。

0 commit comments

Comments
 (0)