sion/chat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
sion
2026-04-25 16:36:34 +08:00
commit db90e7579b
1876 changed files with 189777 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
website/docs/advanced-usage/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Advanced Usage",
"position": 30
}

45
website/docs/advanced-usage/custom-builtin-plugin.md Normal file
View File

@@ -0,0 +1,45 @@
---
sidebar_position: 4
title: Custom Builtin Plugin
---
In Tailchat's plugin center, you can see that the system has builtin some plugins for users to install by default, and these plugins cannot be uninstalled. For self-deployed enterprise users, it is particularly important to have all members install the enterprise or other preset plugins by default.
Next we will learn how to customize the builtin plugin list
*Because plugins are loaded very early, Tailchat is designed to compile the list of builtin plugins into the source code to ensure that the page loads as quickly as possible. Therefore you need to compile the image manually*
First you need to clone the source code:
```bash
git clone https://github.com/msgbyte/tailchat.git
```
Modify the builtin plugin list:
```bash
cd tailchat
vim client/web/src/plugin/builtin.ts
```
Add your configuration file (generally found in the `manifest.json` file in the plugin directory) to the exported variable `builtinPlugins` array according to the existing plugin list format.
:::info
The list of existing plugins can be seen here [Plugin List](/docs/plugin-list/fe)
:::
When the editing is completed, save it and make sure the current directory is in the root directory of tailchat. At this point you should be able to see the `Dockerfile` file directly in your directory.
Execute the command to compile your own image
```bash
docker build -t tailchat .
```
Where `.` represents the current directory, `-t tailchat` represents the compiled tag is `tailchat`, which can be read directly by the `docker-compose.yml` file
After the compilation is completed, just start it according to the normal operation: `docker compose up -d`
:::info
If you compile the image yourself, it is recommended to configure it above **2C4G**
:::

49
website/docs/advanced-usage/external-storage.md Normal file
View File

@@ -0,0 +1,49 @@
---
sidebar_position: 3
title: External Storage
---
## Background
As the usage scale progresses, the user's storage cost for the Tailchat file system will gradually increase, so the privatized deployment of the object storage service `minio` may have high disk storage costs. In order to reduce costs Tailchat provides a solution to use external third-party object storage services
## Prerequisites
- The external storage service needs to support `aws s3` storage protocol
- `Tailchat` version in `1.8.7+`
## Config
You need to configure the environment variables as follows:
- `MINIO_URL`: s3 service address, `<hostname>:<port>`, for example: `example.com:443`, not need protocol part like `https://`
- `MINIO_SSL`: Whether the s3 service enables SSL verification is required for some providers. Default is `false`
- `MINIO_USER`: s3 service username
- `MINIO_PASS`: s3 service password
- `MINIO_BUCKET_NAME`: s3 service bucket name
- `MINIO_PATH_STYLE`: path mode, optional values: `VirtualHosted` or `Path`
- S3 protocol has two style, `VirtualHosted` use in `<bucketname>.example.com`, and `Path` use in `example.com/<bucketname>`
- `STATIC_URL`: The uploaded static path address, which is transferred by the server by default. If you want to directly connect to external storage, you need to change it to an externally accessible address
> For `aliyunoss`, we can refer to this document for content-related help: https://www.alibabacloud.com/help/en/oss/developer-reference/use-amazon-s3-sdks-to-access-oss
### Example
**R2**:
```bash
MINIO_URL=<account-id>.r2.cloudflarestorage.com:443
MINIO_PATH_STYLE=Path
```
## Data migration
If you are migrating from a privately deployed `minio` service to a public cloud, then you need to migrate the old data.
Migration files: `files/**`
You can get the trusted content of the storage volume through `docker volume inspect tailchat_storage`, where `Mountpoint` represents the path, package and upload the `<Mountpoint>/tailchat/files` directory to the corresponding
### Database migration script (optional)
> This is not a necessary operation, because even if you do not migrate, you will follow the original path to transfer to the server
TODO: Welcome to co-construction

55
website/docs/advanced-usage/github-integration.md Normal file
View File

@@ -0,0 +1,55 @@
---
sidebar_position: 2
title: Github integration
---
:::caution
This section is still WIP
:::
![](/img/github-app/github-integration.excalidraw.png)
## Common user use
### Install the application in the project
Link: https://github.com/apps/tailchat
Install into the project repository.
### Configure in the project
Create `.tailchat/topic.json` file in the root directory:
```json
{
"groupId": "<your-notify-group-id>",
"panelId": "<your-topic-panel-id>"
}
```
## Self-host configuration
An application needs to be registered in github before the application starts:
![](/img/github-app/github-new-app.png)
The following environment variables need to be configured during deployment:
- `APP_ID`: from the github app settings
- `WEBHOOK_SECRET`: from the github app settings
- `PRIVATE_KEY`: from the github application settings
- `TAILCHAT_APP_ID`: the id of the Tailchat open platform
- `TAILCHAT_APP_SECRET`: The secret key of Tailchat open platform
- `TAILCHAT_API_URL`: Tailchat backend address
In order to obtain `TAILCHAT_APP_ID` and `TAILCHAT_APP_SECRET`, you need to create an open platform application in the Tailchat open platform
At the same time, enable the robot permission and set the message callback link: `https://<your_app_url>/message/webhook`
### Deploy open platform applications
> Source code: [https://github.com/msgbyte/tailchat/tree/master/apps/github-app](https://github.com/msgbyte/tailchat/tree/master/apps/github-app)
After pulling the source code and deploying it to an accessible online, there are two ways:
- Standalone application: execute `node lib/index.js` after `npm run build` to run the application
- Vercel: just push to Vercel directly

4
website/docs/advanced-usage/openapp/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Open App",
"position": 20
}

34
website/docs/advanced-usage/openapp/about.md Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 1
title: About Open App
---
Open platform is a common and traditional way of interacting between applications. For some simple requirements, we can implement data transfer between applications through an open platform.
In Tailchat. At present, it mainly provides two forms of open platform application capabilities: `OAuth` and `Bot`
## Features
### OAuth
`OAuth` enables external applications to log in through `Tailchat` accounts, just like `Google`, `Github` login methods, which can facilitate users to create a unified user platform based on `Tailchat`
:::info
The difference from the `com.msgbyte.iam` plugin: `iam` plugin provides a way to log in to `Tailchat` with an external account, such as using a `Github` account to log in to `Tailchat`, while the OAuth capability of the open platform is based on `Tailchat` account to log in to other platforms.
:::
[Learn more](./oauth)
### Bot
`Bot` endows chatbots with interactive application capabilities, which means that Tailchat can not only passively receive external messages, but also actively forward internal chat requests to external applications for processing.
[Learn more](./bot)
## Prerequisites
Before using the relevant capabilities of the open platform, please ensure that the corresponding plug-in is installed, and ensure that the administrator has deployed the relevant capabilities of the open platform.
As a user, you need to install the `com.msgbyte.integration` plugin to add the application to your group
As a developer of open platform applications, you need to additionally install `com.msgbyte.openapi` to display the interfaces required by open platform applications

230
website/docs/advanced-usage/openapp/bot.md Normal file
View File

@@ -0,0 +1,230 @@
---
sidebar_position: 3
title: Bot
---
Open platform bot are interactive robot solutions
Main process below:
- Create openapp
- Get appid and appsecret
- Enter the bot page and enable the bot ability
- Fill in the callback address with the public http service address that can be accessed
- Go back to the group page, enter the appid in the group details integration function, find the app you just created, and add it to the group
- In the group @bot and enter text, tailchat will send an http request with message content to the address shown in the callback address
- Receive the request sent by tailchat in the bot service, and send a response to the corresponding panel of the corresponding group through the bot
Of course, [create in Tailchat before you start anything](./create)
Let's take a look at the actual development process of the bot:
## Development with SDK (Node.js)
Tailchat provides sdk as a rapid development tool, `tailchat-client-sdk`, you can install it with the following command
```bash
npm install tailchat-client-sdk
```
Taking `koa` as an example, we first create a simple `koa` service as follows:
Create a node project:
```bash
mkdir tailchat-bot && cd tailchat-bot
npm init -y
npm install koa koa-router tailchat-client-sdk
```
Create `server.js` file:
```js
const Koa = require('koa');
const Router = require('koa-router');
const app = new Koa();
const router = new Router();
// Define route
router.get('/', async (ctx) => {
ctx.body = 'Hello, World!';
});
router.post('/bot/callback', async (ctx) => {
ctx.body = 'Bot Callback Page';
});
// Register middleware
app.use(router.routes());
app.use(router.allowedMethods());
// Start server
app.listen(3000, () => {
console.log('Server is running on http://localhost:3000');
});
```
At this point we have established two basic routes, `/` and `/bot/callback`, and listened to `3000` port, note that `/bot/callback` listens to **POST** requests
At this point we execute `node server.js` to see that our application will be started.
Now we need to add some logic, for example, if we want to implement a repeating bot, then modify the implementation of `/bot/callback` route as follows:
```js
import { TailchatHTTPClient, stripMentionTag } from 'tailchat-client-sdk';
const host = '<your tailchat instance backend host>';
const appId = '<appId>';
const appSecret = '<appSecret>';
const client = new TailchatHTTPClient(host, appId, appSecret)
// ...
router.post('/bot/callback', async (ctx) => {
const type = ctx.body.type;
if (type === 'message') {
const payload = ctx.body.payload;
try {
const message = await client.replyMessage({
messageId: payload.messageId,
author: payload.messageAuthor,
content: payload.messageSnippet
}, {
groupId: payload.groupId,
converseId: payload.converseId,
content: `Your message: ${stripMentionTag(payload.messageSnippet)}`,
})
console.log('send message success:', message)
} catch (err) {
console.log('send message failed:', err)
}
}
ctx.body = 'Bot Callback Page';
});
```
Please fill in `host`, `appId` and `appSecret` into the `appId` and `appSecret` obtained during creation, and `host` into the address of the `Tailchat` server, the official address of `nightly` is `https //tailchat-nightly.moonrailgun.com`
The content of the reply is not important, just make sure not to actively return an error message, Tailchat does not care about the returned content
**Please note that if you want to share your code, please keep your `appSecret`, which is equivalent to your account password**
The logic is very simple. Get the message content, author, id, group id, and converse id from the request. Send content as a reply
Deploy the application online to see the effect.
:::info
Before testing, please make sure you have enabled the bot ability and filled in the correct callback address
:::
## Develop in other languages
Since it is a network application, it is of course not limited to `nodejs`. The following are the formats of some network requests that need to be used, mainly sending requests to the Tailchat server as an open platform bot.
The official `nightly` api address is `https://tailchat-nightly.moonrailgun.com`, please replace it with your own backend address for self-deployment
### Login
Before all requests, you need to log in to obtain the jwt token to indicate your identity, and you need to send the following content:
```
POST /api/openapi/bot/login
Header
Content-Type: application/json
Body
{
appId: <your app id>,
token: <md5(appId+appSecret)>,
}
Response
{
data: {
jwt: "..........",
userId: ".........."
}
}
```
The `token` of the request body is a fixed value, which needs to be encrypted with the `md5` algorithm after splicing `appId` and `appSecret`. Finally get `jwt`, `jwt` must be on the request header in all subsequent requests
```
Header
X-Token: <your-jwt>
```
### Call
Robots can call the interface like ordinary users, such as:
```
POST /api/xxx
Header
Content-Type: application/json
X-Token: <your-jwt>
Body
{
...
}
```
You can treat the bot as an ordinary user. The bot can do everything that ordinary users can do, and the bot will also be subject to the permission restrictions that ordinary users need to be subject to.
The difference is that regular users interact with visualizations, while bots interact with APIs.
#### Send Message
```
POST /api/chat/message/sendMessage
Header
Content-Type: application/json
X-Token: <your-jwt>
Body
{
"converseId": "",
"groupId": "",
"content": "",
"plain": "",
"meta": {},
}
```
#### Reply message
```
POST /api/chat/message/sendMessage
Header
Content-Type: application/json
X-Token: <your-jwt>
Body
{
"converseId": "<converId/panelId>",
"groupId": "<groupId, optional in DM>",
"content": "<your message content>",
"plain": "<your plained message, optional>",
"meta": {
mentions: ["<replyMessageAuthorId>"],
reply: {
_id: "<replyMessageId>",
author: "<replyMessageAuthor>",
content: "<replyMessageContent>",
},
},
}
```
## Additional Documentation
- [Tailchat x Laf: Develop a chatbot in 10 minutes](/blog/tailchat-laf-robot)

14
website/docs/advanced-usage/openapp/create.md Normal file
View File

@@ -0,0 +1,14 @@
---
sidebar_position: 2
title: Create Open Application
---
After installing the `com.msgbyte.openapi` plug-in, you can see an additional open API function on the settings page in the lower left corner
![](/img/advanced-usage/openapp/1.png)
Now, fill in the application name and application description
![](/img/advanced-usage/openapp/2.png)
After success, you can see your open platform application in your application list

94
website/docs/advanced-usage/openapp/oauth.md Normal file
View File

@@ -0,0 +1,94 @@
---
sidebar_position: 5
title: OAuth
---
The `Tailchat` open platform supports the `OAuth` login protocol, and you can easily integrate the `Tailchat` account system into your system. Just like our common `Github Login`, `Google Login`, `Apple Login`
Now, you can use `Tailchat` to implement a unified account management system for your multiple platforms.
## Create a new open platform application in Tailchat
You need to create an open platform application and enable **OAuth** service.
Fill in the address that is allowed to be redirected in **callback address**.
![](/img/advanced-usage/openapp/3.png)
## Create a stand-alone application that initiates and accepts callbacks
First of all, we need to have a general understanding of the basic process of **OAuth** before we officially start
![](/img/advanced-usage/openapp/4.png)
Simply put, it is divided into three steps:
- The first step: access authorization, you need to pass client_id: client id, redirect_uri: redirect uri, response_type is code, scope is the scope of authorization, fill in `openid profile` by default, and state is other custom parameters
- Step 2: After the authorization is passed, it will be redirected to redirect_uri, and the code will be used as its parameter
- Step 3: After getting the code, you can exchange it for an access token, and then you can directly access resources through the token
You can refer to [https://github.com/msgbyte/tailchat/blob/master/server/test/demo/openapi-client-simple/index.ts](https://github.com/msgbyte/tailchat/blob /master/server/test/demo/openapi-client-simple/index.ts) to implement your own OAuth application
### Main process
Here is a brief overview of the process:
First construct a request address, like:
```
<API>/open/auth?client_id=<clientId>&redirect_uri=<redirect_uri>&scope=openid profile&response_type=code&state=123456789
```
in:
- `API` is your tailchat backend address, if you use the default deployment scheme, it is your access address.
- `clientId` is the address of the open platform you applied for in the first step.
- `redirect_uri` is your callback address, you need to make sure it has been added to the whitelist of allowed callback addresses
- `scope` is the scope of application authorization, currently fill in `openid profile` fixedly
- `response_type` is the response type, just fill in `code`
- `state` and other custom parameters will be called with redirection and `code` parameters.
After the user visits this address, it will jump to the Tailchat platform for login authorization. If the authorization is passed, it will be redirected to the address specified by `redirect_uri`. At this time, the receiving address can get `code` and `state` in the query string.
In the next step, we need to exchange `code` for `token` by sending a POST request. Next, we need to use `token` to obtain user information
```
POST <API>/open/token
{
"client_id": clientId,
"client_secret": clientSecret,
"redirect_uri": redirect_uri,
"code": code,
"grant_type": 'authorization_code',
}
```
return value:
```
{
access_token,
expires_in,
id_token,
scope,
token_type
}
```
At this point we got the `access_token`, which we can use to request user information:
```
POST <API>/open/me
{
"access_token": access_token,
}
```
return value:
```
{
sub,
nickname,
discriminator,
avatar,
}
```
Among them, `sub` can be understood as the user's id, which is the unique identifier of the user

49
website/docs/advanced-usage/openapp/ws.md Normal file
View File

@@ -0,0 +1,49 @@
---
sidebar_position: 4
title: Websocket Bot
---
In addition to traditional HTTP callback bots, we also support bots based on the websocket long connection protocol.
The long-connection robot can listen to all messages like a normal user, and does not need to be invoke by `@`.
Of course, the disadvantage is that it is not convenient for some platforms that only support http requests, such as `serverless` and other platforms that do not support `websocket`. And currently only the `nodejs` version is implemented.
Here is an example in here:
```ts
import { TailchatWsClient } from 'tailchat-client-sdk';
const HOST = process.env.HOST;
const APPID = process.env.APPID;
const APPSECRET = process.env.APPSECRET;
if (!HOST || !APPID || !APPSECRET) {
console.log('require env: HOST, APPID, APPSECRET');
process. exit(1);
}
const client = new TailchatWsClient(HOST, APPID, APPSECRET);
client.connect().then(async() => {
console.log('Login Success!');
client.onMessage((message) => {
console.log('Receive message', message);
});
});
```
Among them, `HOST`, `APPID`, `APPSECRET` represent the server address, the id and secret key of the open platform respectively.
**Please do not upload your secret key on the public platform, the secret key is equivalent to the password**
This operation creates an event listener after connecting to the server, and when any message is received, the content of the message will be printed out.
Similarly, if we need to subscribe the update event of the message, we can use the subscribe message update operation
```ts
client.onMessageUpdate((message) => {
console.log('Receive message', message);
});
```

4
website/docs/advanced-usage/plugins/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Plugin Document",
"position": 10
}

16
website/docs/advanced-usage/plugins/com.msgbyte.autojoinGroup.md Normal file
View File

@@ -0,0 +1,16 @@
---
sidebar_position: 4
title: auto join group
---
`com.msgbyte.autojoinGroup`
Just need config environment: `AUTOJOIN_GROUP_ID=xxxxx` and restart server
You should create group from admin or web app manually. and then you can get a groupId.
In web app, you can get groupId from url, for example: `/main/group/<groupId>/<panelId>`
> If you wanna join more than one group after user register, you can split with `,`
>
> For example: AUTOJOIN_GROUP_ID=xxxxx,xxxx

40
website/docs/advanced-usage/plugins/com.msgbyte.iam.md Normal file
View File

@@ -0,0 +1,40 @@
---
sidebar_position: 3
title: iam - Third party login
---
`com.msgbyte.iam`
The `IAM` plugin provides third-party login functionality
Currently supported:
- github
## Configuration Method
### Github
Create an OAuth application in `Github`. Get `Client ID` and `Client secrets`
Configure the authorization callback address `Authorization callback URL` of the `Github` application to `{API_URL}/api/plugin:com.msgbyte.iam/github/redirect`. Note that `API_URL` is the value in the environment variable, and the two should be consistent.
Configure Tailchat environment variables:
- IAM_GITHUB_ID
- IAM_GITHUB_SECRET
Respectively, `Client ID` and `Client secrets` obtained before
> You also can use env to overwrite uri, for example use proxy:
>
> - IAM_GITHUB_URI_AUTHORIZE=https://github.com/login/oauth/authorize
> - IAM_GITHUB_URI_ACCESS_TOKEN=https://github.com/login/oauth/access_token
> - IAM_GITHUB_URI_USERINFO=https://api.github.com/user
## Security Protection
In order to prevent tokens from being obtained by malicious applications, it is recommended to add front-end domain name verification.
Just configure `IAM_FE_URL` in the environment variable, and the value is the front-end domain name. Such as: `IAM_FE_URL=http://localhost:11011`
> for `window.opener.postMessage(<data>, "IAM_FE_URL")`

35
website/docs/advanced-usage/plugins/com.msgbyte.livekit.md Normal file
View File

@@ -0,0 +1,35 @@
---
sidebar_position: 5
title: livekit - Video Conference
---
`com.msgbyte.livekit`
## User documentation
This plugin provides `Tailchat` video conferencing function, after installing the plugin you can create a voice channel.
After installation, you can see a new panel type named voice channel on the create panel modal
![](/img/advanced-usage/plugins/livekit/1.png)
The voice channel entry is probably like this:
![](/img/advanced-usage/plugins/livekit/2.png)
You can prepare multimedia options and switch media devices before joining.
Of course, you can switch devices at any time after joined. like below:
![](/img/advanced-usage/plugins/livekit/3.png)
You can freely video call, share your screen, and chat with your friends.
Finally, please switch pages freely, this will not let you exit the channel, you can click the icon in the lower left corner to quickly return to the active channel at any time.
![](/img/advanced-usage/plugins/livekit/4.png)
## Deployment documentation
See tutorial [livekit](../../meeting/livekit.md)

10
website/docs/advanced-usage/plugins/com.msgbyte.wxpusher.md Normal file
View File

@@ -0,0 +1,10 @@
---
sidebar_position: 2
title: wxpusher
---
`com.msgbyte.wxpusher`
:::caution
This plugin just make for chinese mainland user which use wechat. please switch language to `zh-Hans` to continue.
:::

34
website/docs/advanced-usage/richtext.md Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 1
title: Rich text syntax
---
## For normal users
Tailchat has a built-in `com.msgbyte.bbcode` plugin for rich text message support (and it is installed by default).
The following is a list of syntaxes currently supported by the `bbcode` plugin:
| Keyword | Description | Usage Example | Preview |
| ------ | ----- | ------ | ----- |
| b | bold text | `[b]foo[/b]` | <b>foo</b> |
| i | text italic | `[i]foo[/i]` | <i>foo</i> |
| u | underline text | `[u]foo[/u]` | <ins>foo</ins> |
| s | strikethrough text | `[s]foo[/s]` | <del>foo</del> |
| url | hyperlink | <div style={{width: 400}}>`[url]https://tailchat.msgbyte.com[/url]` / `[url=https://tailchat.msgbyte.com ]Official website[/url]`</div> | <a>https://tailchat.msgbyte.com</a> / <a href="https://tailchat.msgbyte.com">official website</a> |
| img | image | `[img]https://tailchat.msgbyte.com/img/logo.svg[/img]` | <div style={{width: 60}}><img src="https:/ /tailchat.msgbyte.com/img/logo.svg" /></div> |
| at | mention user | `[at=<hereisuserid>]moonrailgun[/at]` | - |
| emoji | expression | `[emoji]smile[/emoji]` | - |
| markdown / md | markdown syntax support | `[markdown]## Heading[/markdown]` / `[md]## Heading[/md]` | - |
## For plugin developers
If your plugin needs to use unified rich text support, please implement this in your rendering function:
```jsx
import { getMessageRender } from '@capital/common';
const Component = (text: string) => {
return <div>{getMessageRender(text)}</div>
}
```

12
website/docs/architecture.md Normal file
View File

@@ -0,0 +1,12 @@
---
sidebar_position: 3
title: System Architecture
---
## Backend Architecture
![](/img/architecture/backend.excalidraw.svg)
## Plugin mechanism architecture
![](/img/architecture/plugin.excalidraw.svg)

4
website/docs/benchmark/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Benchmark",
"position": 50
}

112
website/docs/benchmark/cli.md Normal file
View File

@@ -0,0 +1,112 @@
---
sidebar_position: 1
title: Cli Test Method
---
First of all, you need to make sure that `tailchat-cli` has been installed, and the version is above `1.5.8`. For the installation method, see: [tailchat-cli](../cli/tailchat-cli.md)
You can see the following commands supported by benchmark in the Help command of Tailchat:
```
tailchat benchmark
Tailchat Benchmark Test
Commands:
tailchat benchmark message Stress testing through Tailchat network
requests (suitable for pure business
testing)
tailchat benchmark connections <url> Test Tailchat Connections
tailchat benchmark register <url> Create Tailchat temporary account and
output token
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
```
Among them, we mainly use the `connections` command and the `register` command
## Register test users in batches
First of all, we need to register test users in batches, here we need to use the `register` command
```
tailchat benchmark register <url>
Create Tailchat temporary account and output token
Options:
--version Show version number [boolean]
--file Account Token Path [string] [required] [default: "./accounts"]
--count Register Count [number] [required] [default: 100]
--invite Invite Code [string]
-h, --help Show help [boolean]
--url
```
If we need to register accounts locally in batches
```bash
tailchat benchmark register http://127.0.0.1:11000
```
This command will register 100 temporary users under `http://127.0.0.1:11000` service. Note that the '/' is not required at the end.
After the command is executed, the token used for login will be saved to a local file, the default is `./accounts` file.
We can use `--count` to specify the number of registrations, and `--invite` to let it automatically join a test group after registration
like:
```bash
tailchat benchmark register http://127.0.0.1:11000 --count 10000 --invite <invite-code>
```
> Note: In order to ensure the quality of service, the register operation is sent in a serial manner, that is, the subsequent register operation will start after the previous register operation is completed. Therefore, if the number of settings is too large, it may take a long time.
Among them, `<invite-code>` requires the user to create a group and create an invitation link. The format of an invite link is: `http://localhost:11011/invite/<invite-code>`
After completion, we can get the corresponding number of test users to join the group.
## User batch login
We want to test the performance of the server when multiple people are allowed online, we need to use the `connections` command to log in and establish a connection.
The `connections` command will automatically read the token file after batch registration in the previous operation as the user who needs to log in
```
tailchat benchmark connections <url>
Test Tailchat Connections
Options:
--version Show version number [boolean]
--file Account Token Path
[string] [required] [default: "./accounts"]
--groupId Group Id which send Message [string]
--converseId Converse Id which send Message [string]
-h, --help Show help [boolean]
--url [required]
```
If we want to log in directly to the local service:
```bash
tailchat benchmark connections http://127.0.0.1:11000
```
At this point, we can use the resource detection tool on the server to check the memory usage and CPU usage of the server after all test users are online.
### Message push/receive time detection
In order to test the performance of the Tailchat chat server in an actual session, we can measure the time it takes for a message to be sent from the client to the server and for the server to broadcast the message to all users.
Here we need to specify the target to send the message, as follows:
```bash
tailchat benchmark connections http://127.0.0.1:11000 --groupId <groupId> --converseId <converseId>
```
The format of the address bar in a group session is: `http://localhost:11011/main/group/<groupId>/<converseId>`
When all sessions are accepted, the time spent during the period will be printed

237
website/docs/benchmark/report.md Normal file
View File

@@ -0,0 +1,237 @@
---
sidebar_position: 2
title: Benchmark Report
---
## Cluster benchmark test
:::info
Test version: v1.7.6
Basic information of the test cluster:
- mongo: **0.2**cpu **256**Mi memory single instance
- redis: **0.1**cpu **64**Mi memory single instance
- minio: **0.1**cpu **128**Mi memory single instance
- tailchat: **0.2**cpu **512**Mi memory 3 instances
> The test service is a complete service, that means, a complete service loaded with services and plugins, without any directional optimization for data to look good (better performance can be obtained by controlling the services that reduce loading and turning off some unnecessary capabilities )
>
> Among them, the cpu model is: `Intel(R) Xeon(R) CPU @ 2.20GHz`
>
> The server network uses `Singapore Google Cloud`, and the test machine uses `Telecom Shanghai`. Actually, there is a certain network loss. The cluster service is provided by sealos for this pressure test.
:::
### Test method
The test mode consists of an actual observer + several virtual users started by cli. See the test method: [cli](./cli.md)
The main commands are as follows:
```
tailchat benchmark register https://<xxxxxx>.cloud.sealos.io --invite <inviteCode>
tailchat benchmark connections https://<xxxxxx>.cloud.sealos.io
tailchat benchmark connections https://<xxxxxx>.cloud.sealos.io --groupId <groupId> --converseId <converseId> --messageNum 5
```
> The following descriptions about cpu/memory are the average value of multiple instances
### 100 user online test
#### Online Status
When only one actual user is logged in, the system occupancy is:
- cpu: 0.90%
- Memory: 176.3 Mi
After logging in 100 online users, the system occupancy is:
- cpu: 14.80 % -> 8.89% -> 1.33% (because the actual observer gets all 100 user online information at one time)
- Memory: 179.37 Mi
#### Message sending status
Test the sending and receiving of all messages 5 times
```
✔ 100 clients have been created.
Start send message test: 1
ℹ Start message receive test, message: 0c55e168904f02a3
✔ All client received, usage: 420ms
Start send message test: 2
ℹ Start message receive test, message: 6f000fb91dc85fe1
✔ All client received, usage: 89ms
Start send message test: 3
ℹ Start message receive test, message: 79cce2beee015c5f
✔ All client received, usage: 89ms
Start send message test: 4
ℹ Start message receive test, message: 8df7c58fdadb30aa
✔ All client received, usage: 96ms
Start send message test: 5
ℹ Start message receive test, message: 97c782b36312022c
✔ All client received, usage: 98ms
```
### 500 user online test
#### Online Status
When no user is logged in, the system occupancy is:
- cpu: 0.92%
- Memory: 208.5533 Mi
After logging in 500 online users, the system occupancy is:
- cpu: 3.30%
- Memory: 241.1933 Mi
#### Message sending status
Test the sending and receiving of all messages 5 times
```
✔ 500 clients have been created.
Start send message test: 1
ℹ Start message receive test, message: ef39144e96ce3ab8
✔ All client received, usage: 497ms
Start send message test: 2
ℹ Start message receive test, message: 5a86b397aab8ff92
✔ All client received, usage: 406ms
Start send message test: 3
ℹ Start message receive test, message: 69066c6d4a4402b0
✔ All client received, usage: 403ms
Start send message test: 4
ℹ Start message receive test, message: 3b066befc54b4835
✔ All client received, usage: 424ms
Start send message test: 5
ℹ Start message receive test, message: 3a6ef9cc7e8e6eac
✔ All client received, usage: 752ms
```
### 1k user online test
#### Online Status
When no user is logged in, the system occupancy is:
- cpu: 0.88%
- Memory: 202.978 Mi
> When I establish more than 800 connections, a large number of `transport close` errors will be triggered and the connection cannot be established
>
> In order to be able to carry 1000 people at the same time, I choose to expand the capacity horizontally and expand the number of instances to 5 instances
After logging in 1000 online users, the system occupancy is:
- cpu: 3.27%
- Memory: 210.876 Mi
#### Message sending status
Test the sending and receiving of all messages 5 times
```
✔ 1000 clients have been created.
Start send message test: 1
ℹ Start message receive test, message: e65050aa6d4237bb
✔ All client received, usage: 2194ms
Start send message test: 2
ℹ Start message receive test, message: a7b02d30e25f02d0
✔ All client received, usage: 954ms
Start send message test: 3
ℹ Start message receive test, message: 75aa655a94cb308f
✔ All client received, usage: 988ms
Start send message test: 4
ℹ Start message receive test, message: 106b8830443002d9
✔ All client received, usage: 733ms
Start send message test: 5
ℹ Start message receive test, message: 0593646f9c7da288
✔ All client received, usage: 738ms
```
## Standalone benchmark test
:::info
Test version: v1.7.6
Basic information of the test environment:
- NAS deployment dependency (DS220plus): Intel Celeron J4025, 2GB DDR4
-mongo
- redis
-minio
- PC, cpu: i7-8700K, 32G memory
- tailchat
:::
### 2k user online test
#### Message sending status
Test the sending and receiving of all messages 5 times
```
✔ 2000 clients have been created.
Start send message test: 1
ℹ Start message receive test, message: 8f4edd63886d80eb
✔ All client received, usage: 244ms
Start send message test: 2
ℹ Start message receive test, message: 20e0bc3e2ea1365c
✔ All client received, usage: 246ms
Start send message test: 3
ℹ Start message receive test, message: 7bed6a2cb12238a5
✔ All client received, usage: 248ms
Start send message test: 4
ℹ Start message receive test, message: 6f49353efa2467fc
✔ All client received, usage: 245ms
Start send message test: 5
ℹ Start message receive test, message: 850bed7ed8fa860c
✔ All client received, usage: 248ms
```
### 5k user online test
#### Message sending status
Test the sending and receiving of all messages 5 times
```
✔ 5000 clients have been created.
Start send message test: 1
ℹ Start message receive test, message: 85e2624234b8c66a
✔ All client received, usage: 933ms
Start send message test: 2
ℹ Start message receive test, message: ae025dd881ef5ae7
✔ All client received, usage: 714ms
Start send message test: 3
ℹ Start message receive test, message: 55a6c359fe74c90f
✔ All client received, usage: 691ms
Start send message test: 4
ℹ Start message receive test, message: 9eaefcc761c77c8c
✔ All client received, usage: 644ms
Start send message test: 5
ℹ Start message receive test, message: 856a49a1528ad5e1
✔ All client received, usage: 787ms
```
### 10k user online test
#### Message sending status
Test the sending and receiving of all messages 5 times
```
✔ 10000 clients has been create.
Start send message test: 1
ℹ Start message receive test, message: 06b6bf829b66cca9
✔ All client received, usage: 1219ms
Start send message test: 2
ℹ Start message receive test, message: 3a544d3c0e6d8a14
✔ All client received, usage: 1189ms
Start send message test: 3
ℹ Start message receive test, message: b1d0ea01481b6717
✔ All client received, usage: 1089ms
Start send message test: 4
ℹ Start message receive test, message: af3512e57ce2ad0e
✔ All client received, usage: 1142ms
Start send message test: 5
ℹ Start message receive test, message: d09db4b9a348b32a
✔ All client received, usage: 1232ms
```

4
website/docs/cli/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Cli",
"position": 40
}

34
website/docs/cli/tailchat-cli.md Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 1
title: tailchat-cli
---
## Install
```bash
npm install -g tailchat-cli@latest # Install and update with the same command
```
or directly use
```bash
npx tailchat-cli <command>
```
After the installation is successful, enter `tailchat` and return as follows:
```bash
tailchat <command>
Commands:
tailchat create [template] Create Tailchat repo code
tailchat connect Connect to Tailchat network
tailchat bench Benchmark
tailchat declaration <source> Tailchat plugin type declaration
tailchat docker Tailchat image management
tailchat usage [pid] View Tailchat process usage
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
```

4
website/docs/contribution/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Contribution",
"position": 90
}

28
website/docs/contribution/community.md Normal file
View File

@@ -0,0 +1,28 @@
---
sidebar_position: 99
title: Ecology & Community
---
`Tailchat` is a very open platform and welcomes contributions in any form from everyone. Here are some third-party resources related to `Tailchat`
Feel free submit `pr/issue` to submit your contribution to `Tailchat`, so that we can include it in the following list:
## Exchange community
[Join TailchatNightly Channel](https://nightly.paw.msgbyte.com/invite/8Jfm1dWb)
## Project/Code
- [Tailchat-Assistant](https://git.povario.com/powermaker450/Tailchat-Assistant): Tailchat Assistant is your very own AI-powered chat bot, ready to implement into your guild!
## Video
- [【好玩儿的Docker项目】激情畅聊！十分钟搭建一个插件化易拓展的开源即时聊天（IM）应用——Tailchat](https://www.bilibili.com/video/BV1aG411u7M8/)
- [简单搭建插件化易拓展的开源即时聊天（IM）应用——Tailchat](https://www.bilibili.com/video/BV1UN4y117M8/)
## Article
- [【好玩儿的Docker项目】激情畅聊！十分钟搭建一个插件化易拓展的开源即时聊天（IM）应用——Tailchat](https://blog.laoda.de/archives/docker-compose-install-tailchat)
- [Tailchat Synology deployment record](/blog/2023/03/27/deploy-in-synology)
- [微信公众号: 重磅推荐：一个开源的即时通讯应用 Tailchat(from GitHub黑板报)](https://mp.weixin.qq.com/s/uImzeb_EQdQcm9LGGwGYuw)

4
website/docs/contribution/dev/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Development Documentation",
"position": 2
}

76
website/docs/contribution/dev/role.md Normal file
View File

@@ -0,0 +1,76 @@
---
sidebar_position: 1
title: Identity Groups and Permissions
---
Identity groups are a form of dividing user authority points in group management (RBAC).
An identity group is composed of a series of permission point switches, and a user may be composed of multiple identity groups. For example, identity group A has A permission, and identity group B has B permission. User C in group A and identity group B has permission A and permission B. In order to simplify the design of permissions, permission points are implemented through simple `true/false`
More about `RBAC` can be found in the related wiki: https://en.wikipedia.org/wiki/Role-based_access_control I won’t go into details here.
The following mainly talks about how to add/modify permission points in `Tailchat`
## Built-in permissions
Permission points need to be declared on both the front-end and back-end at the same time. The front-end is responsible for the display of the front-end, and the back-end is responsible for the comprehensive permission verification. If there is no permission, the processing interface should directly throw an error.
### Frontend Management
The permission point list of the front end is maintained in `client/shared/utils/role-helper.ts`, including the permission point of the permission point, such as:
```tsx
export const PERMISSION = {
/**
* Non-plugin permission points are called core
*/
core: {
message: 'core.message',
},
};
```
And the display of the permission point on the management page:
```tsx
export const getPermissionList = (): PermissionItemType[] => [
{
key: PERMISSION.core.message,
title: t('Send Message'),
desc: t('Allow members to send messages in text channel'),
default: true,
}
];
```
The way to use it is to obtain the permission points maintained under the group through hooks:
```tsx
const [allowSendMessage] = useHasGroupPermission(groupId, [
PERMISSION.core.message,
]);
```
The way of using arrays is convenient for some business logics that need to have multiple permission points.
### Backend
The permission statement of the backend is maintained in `server/packages/sdk/src/services/lib/role.ts`, and the usage method is very simple. as follows:
```ts
const [hasPermission] = await call(ctx).checkUserPermissions(
groupId,
userId,
[PERMISSION.core.message]
);
if (!hasPermission) {
throw new NoPermissionError(t('no operation permission'));
}
```
## Plugin permissions
TODO

64
website/docs/contribution/guide.md Normal file
View File

@@ -0,0 +1,64 @@
---
sidebar_position: 1
title: Contribution Guidelines
---
`Tailchat` is a very open project and welcomes contributions of any kind from all backgrounds. Its plugin architecture is meant to allow `Tailchat` to host the implementation of any idea.
We hope that `Tailchat` is not just a simple chat application, but a space to connect different tools and different ideas.
Github link: https://github.com/msgbyte/tailchat
-----------
Contributor roles are currently urgently needed for `Tailchat`:
### Front-end plugin developer
- Familiar with the use of React
- Possess certain abstract thinking
- Have basic aesthetic ability
- Passionate about open source projects
### Backend plugin developers
- Familiar with the use of Nodejs
- Have a basic understanding of microservices
- Passionate about open source projects
### electron application developer
- Understand cross-platform development
- Familiar with code injection, able to realize data interaction between render process and main
- Passionate about open source projects
### React Native App Developers
- Familiar with the development of React Native applications
- Familiar with the use of React Native Web
- Passionate about open source projects
### Operation Classmates
- Understand basic operational capabilities and have experience as a group leader
- Understand the publicity channels and methods of open source projects
- Strong communication skills
- Passionate about open source projects
### Ambassador
- Master the mother tongue and English (if English is the mother tongue, only English is enough)
- Have a certain understanding of the open source community
- Participate in the development of Tailchat usage and best practices
- Strong communication skills
- Passionate about open source projects
### other
More of all possibilities...
:::info
Contact: Send an email to `moonrailgun@gmail.com` or [Join TailchatNightly Channel](https://nightly.paw.msgbyte.com/invite/8Jfm1dWb)
:::

4
website/docs/deployment/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Application Deployment",
"position": 10
}

42
website/docs/deployment/admin.md Normal file
View File

@@ -0,0 +1,42 @@
---
sidebar_position: 9
title: Deployment admin platform (optional)
---
:::info
The feature of `admin` is still being iterated, and it is currently in the early trial version
We will continue to enrich the internal content in the future
:::
Get the latest `admin` configuration from `github`:
```bash
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker/admin.yml
```
Set the account and password of the `admin` in the environment variable `docker-compose.env`:
```ini
ADMIN_USER=tailchat
ADMIN_PASS=<Write the independent background password here, do not tell others>
```
Then use [Multiple Files](https://docs.docker.com/compose/extends/#understanding-multiple-compose-files) to start the application:
```bash
docker compose -f docker-compose.yml -f admin.yml up -d
```
*Pay attention to the order, because `admin.yml` depends on `docker-compose.yml`, so it should be placed behind*
At this time, add `/admin/` after the access backend address to access:
```
https://tailchat.example.com/admin/
```
*Note: don't forget to have a `/` at the end*
<details>
<summary>About the deprecated legacy admin</summary>
admin-old will be remove in v1.8.6. you can checkout version before to get it
</details>

BIN
website/docs/deployment/assets/docker-init.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 169 KiB

34
website/docs/deployment/cdn.md Normal file
View File

@@ -0,0 +1,34 @@
---
sidebar_position: 11
title: CDN Deployment (optional)
---
There may be cases where front-end and back-end are deployed separately. For example, if you want to manage front-end code separately in object storage, add CDN support. You need to compile the front-end code separately.
Backend code is still recommended to use `docker` to deploy
In order to compile the front-end code separately, you need to download the source code and compile it manually
```bash
git clone https://github.com/msgbyte/tailchat.git
cd tailchat
# You can switch between different distributions by git, for example: git checkout v1.8.8
pnpm install # You need to use `pnpm` to install dependencies, using other package management tools may cause problems. and you should use pnpm@8 because here is some break change in pnpm@9
```
Wait patiently for dependencies to be installed
Enter the front-end code and compile it
```bash
cd client/web
SERVICE_URL=<your-api-url> pnpm build
```
Make sure the value of `SERVICE_URL` is the address of your api backend, for example: `http://127.0.0.1:11000`
After compiling, you can get all the front-end files in the `tailchat/client/web/dist` directory.
> In addition, if there is a 404 report after refreshing the page, you need to configure a configuration similar to [When hosting a static website, set the index.html file in the root directory as the default home page]

85
website/docs/deployment/dev.md Normal file
View File

@@ -0,0 +1,85 @@
---
sidebar_position: 99
title: Development environment
---
For setting up the development environment, tailchat provides a very simple and fast way:
## Use Docker to quickly build a dependent environment
**mongodb**
```bash
docker run -d --name mongo -p 27017:27017 mongo:4
```
**redis**
```bash
docker run -d --name redis -p 6379:6379 redis
```
**minio**
```bash
docker run -d \
-p 19000:9000 \
-p 19001:9001 \
--name minio \
-e "MINIO_ROOT_USER=tailchat" \
-e "MINIO_ROOT_PASSWORD=com.msgbyte.tailchat" \
minio/minio server /data --console-address ":9001"
```
### Example
Here is a minimal example `.env` which let you can run tailchat in development environment.
```ini
PORT=11000
MONGO_URL=mongodb://127.0.0.1:27017/tailchat
REDIS_URL=redis://localhost:6379/
MINIO_URL=127.0.0.1:19000
MINIO_USER=tailchat
MINIO_PASS=com.msgbyte.tailchat
```
## Node Version
Tailchat is develop with `nodejs`, please install nodejs by yourself, here is nodejs official: [https://nodejs.org/](https://nodejs.org/)
Suggestion to use `nodejs18.x`, and not support `nodejs20` yet because nodejs has some break change.
## Start the development server
```bash
pnpm install
pnpm dev
```
You can edit the configuration of `server/.env` to your own relevant context
The file can be started from `server/.env.example`
Now you can preview your server in `http://localhost:11011`
## Project directory description
- `apps`: non-core applications
- `cli`: Tailchat’s command line program
- `github-app`: Tailchat’s github integration bot
- `oauth-demo`: Tailchat open platform third-party login demo program
- `widget`: Web page embedded widget
- `client`: client
- `desktop`: desktop version
- `mobile`: mobile version
- `packages`: dependency packages
- `shared`: platform-independent common code
- `web`: web version
- `plugins`: pure frontend plugins
- `src`: source code
- `packages`
- `types`: common types for both front and back ends
- `server`: server
- `admin`: background management
- `models`: database model
- `plugins`: server-side plugins
- `services`: microservices
- `website`: official website

187
website/docs/deployment/docker-compose.mdx Normal file
View File

@@ -0,0 +1,187 @@
---
sidebar_position: 4
title: Docker Compose deployment
---
## Recommended configuration
Recommended minimum configuration **1 core 2G**
> If there is only **1 core 1G**? Please refer to my blog: [Linux small resource server experience summary](http://moonrailgun.com/posts/6769ba51/) expand memory space by swapping memory
>
> Memory usage for reference:
> ![](/img/misc/memory-usage.png)
## Pre-environment
### Docker / Docker Compose
First you need to make sure you have a `Docker / Docker Compose` environment
The installation method can refer to: [Install the docker environment](./install-docker.md)
## Pull Image
You can pull the compiled image from **public image** or **manually compile from source code**
> Using the compiled image can compile without spending enough computer resources, which is very friendly to servers with small resource configurations. In addition, compared to source code compilation, the code of the public image is more stable.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs groupId="build">
<TabItem value="cli" label="One-command installation using cli" default>
> Use `cli` Please make sure you already have a node environment on your server (node version 16+ is recommended)
> If you don't know about node, you can use `Manually install from public image`
Use the command line tool `tailchat-cli` to pull/update the image with one click:
```bash
npx tailchat-cli docker update
```
</TabItem>
<TabItem value="public-image" label="Manually install from public image" default>
Manually install using Docker native commands:
```bash
docker pull moonrailgun/tailchat # Pull the tailchat image from the public image registry
docker tag moonrailgun/tailchat tailchat # Retag the downloaded image to tailchat (consistent with source code compilation, if not changed, it will follow the source code compilation process)
```
:::info
You can view historically supported image versions from [Docker Hub](https://hub.docker.com/r/moonrailgun/tailchat/tags)
:::
</TabItem>
<TabItem value="source-code" label="Compile from source">
*This section is for advanced players to get the latest tailchat implementation, please make sure you have enough knowledge of `docker`, `nodejs`, `git`*
#### Compilation environment
- Download from [official website](https://nodejs.org/en/download/)
- Or use [nvm](https://github.com/nvm-sh/nvm)
#### Install pnpm
`pnpm` is a package management tool for `nodejs`, a substitute for `npm`, in order to ensure the same dependency environment as developers, it is strongly recommended that you use pnpm as a follow-up package management tool
```bash
npm install -g pnpm
```
#### Clone Repo
Download the project from remote:
```bash
mkdir msgbyte && cd msgbyte
git clone https://github.com/msgbyte/tailchat.git # Clone the project to local
```
#### Compile project
```bash
cd tailchat && docker compose build
```
*Compilation has certain requirements on server configuration, 2-core 4G compilation takes about 10 minutes, for reference*
After the compilation is complete, you can view the compiled image through `docker images`.
</TabItem>
</Tabs>
## Startup project
<Tabs groupId="build">
<TabItem value="cli" label="One-command installation using cli" default>
```bash
npx tailchat-cli docker init
```
Executing this command will ask you some configuration-related questions in an interactive manner (as shown in the figure below), and the configuration file will be automatically generated after filling it out
![](./assets/docker-init.png)
</TabItem>
<TabItem value="public-image" label="Manually install from public image">
> A configuration file needs to be downloaded before starting to tell `docker-compose` how to start the image
> Download configuration files and configure environment variables from the repository:
> - [docker-compose.yml](https://raw.githubusercontent.com/msgbyte/tailchat/master/docker-compose.yml)
> - [docker-compose.env](https://raw.githubusercontent.com/msgbyte/tailchat/master/docker-compose.env)
```bash
mkdir tailchat && cd tailchat
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker-compose.yml
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker-compose.env
```
Need to modify the configuration before starting
Modify the configuration of the `docker-compose.env` file, the following fields are recommended to be modified:
- `API_URL` is an externally accessible url address, used for file service access, it can be a domain name or an ip **If the sent picture cannot be displayed normally, this variable is not set**
- `SECRET` server-side encryption key, used to generate Token. The default is `tailchat`
</TabItem>
<TabItem value="source-code" label="Compile from source">
Need to modify the configuration before starting
Modify the configuration of the `docker-compose.env` file, the following fields are recommended to be modified:
- `API_URL` is an externally accessible url address, used for file service access, it can be a domain name or an ip **If the sent picture cannot be displayed normally, this variable is not set**
- `SECRET` server-side encryption key, used to generate Token. The default is `tailchat`
</TabItem>
</Tabs>
After completing the configuration, use `docker-compose` to start the `Tailchat` application with one click:
```bash
# Make sure the configuration files (docker-compose.yml and docker-compose.env) are in the current directory
# Execute the following command to start with one key
docker compose up -d
```
Visit: `http://<server ip>:11000` to open tailchat.
Note that some cloud services may need to manually open firewall ports.
*Some environment variables are provided in the `docker-compose.env` file for configuration.*
The `docker-compose.yml` configuration of `tailchat` provides the following configuration by default:
- `mongodb`: Persistent Database
- `redis`: KV database and message transport service
- `minio`: Distributed file service
The persistent files (database, file storage) are managed uniformly through `docker volume`:
```
docker volume ls | grep "tailchat-server"
```
:::info
Complete environment variables can be queried [Environment Variables](./environment.md)
:::
## More deployment related documents
- [Build https gateway (optional)](./https-gateway.md)
- [Deployment admin platform (optional)](./admin.md)

79
website/docs/deployment/environment.md Normal file
View File

@@ -0,0 +1,79 @@
---
sidebar_position: 7
title: Environment Variable
---
## Environment Variable
| Name | Default Value | Description |
| ----- | ------ | --- |
| PORT | 11000 | Gateway service port number |
| SECRET | tailchat | encryption key, used for JWT |
| STATIC_HOST | "{BACKEND}" | Externally accessible static service host, used for file service access, the default is the dynamic server address inferred from the front-end request, if it is expected to be stored in a third-party OSS, it needs to be modified |
| STATIC_URL | "{BACKEND}/static/" | Externally accessible static service complete address prefix, used for file service access, the default is the dynamic server address inferred from the front-end request, if it is expected to be stored in a third-party OSS Modify, if this variable is set, the above `STATIC_HOST` value is invalid |
| API_URL | http://127.0.0.1:11000 | Externally accessible url address, used for issuer issuance on open platforms or as a fallback for file services |
| MONGO_URL | - | Database service address |
| REDIS_URL | - | Redis service address |
| MINIO_URL | - | File service address (minio) |
| MINIO_USER | - | File service username |
| MINIO_PASS | - | File service password |
| MINIO_BUCKET_NAME | tailchat | file service bucket name |
| MINIO_PATH_STYLE | false | Whether to use path-style s3 communication format, `true` is `Path Style`, `false` is `Virtual hosted style` |
| MINIO_SSL | false | Whether to use SSL to connect storage, if "1" or "true" enable SSL |
| SMTP_SENDER | - | Mail service sender (example: `"Tailchat" example@163.com`) |
| SMTP_URI | - | mail service connection address (example: `smtp://username:password@smtp.example.com/?pool=true`) |
| FILE_LIMIT | 1048576 | File/image upload size limit, the default is 1m, please enter a number(unit: byte) |
| EMAIL_VERIFY | - | Whether to enable email verification, if it is "1" or "true", add email verification control when registering |
| REQUEST_TIMEOUT | 10000 | Number of milliseconds to wait before reject a request with a RequestTimeout error. Disabled: 0 |
| TIANJI_SCRIPT_URL | - | Script Url of Tianji if you wanna monitor Tailchat user usage, you can get it in code modal in Tianji website (example: `https://tianji.example.com/tracker.js`) |
| TIANJI_WEBSITE_ID | - | Tianji website id |
| DISABLE_MESSAGEPACK | - | Whether to disable using messagepack as [parser](https://socket.io/docs/v4/custom-parser/) for socketio in openapi, if "1" or "true" turn off this method |
| DISABLE_LOGGER | - | Whether to disable the log output, if "1" or "true" turn off the log on the fly |
| DISABLE_TRACING | - | Whether to disable the Tracing function (enabling it can save a lot of logs), if "1" or "true" turn off the log on the fly |
| DISABLE_USER_REGISTER | - | Whether to disable the user register, if "1" or "true" turn off this method |
| DISABLE_GUEST_LOGIN | - | Whether to disable the guest login, if "1" or "true" turn off this method |
| DISABLE_CREATE_GROUP | - | Whether to disable user create group, if "1" or "true" turn off this method |
| DISABLE_PLUGIN_STORE | - | Whether to hide user plugin store entry, if "1" or "true" turn off this method |
| DISABLE_ADD_FRIEND | - | Whether to hide user add friend entry, if "1" or "true" turn off this method |
| DISABLE_TELEMETRY | - | Whether to disable send telemetry report to msgbyte to help us improve, its anonymous, if "1" or "true" turn off telemetry |
> Some examples of environment variables can be seen: https://github.com/msgbyte/tailchat/blob/master/server/.env.example
### Use files to configure environment variables
- - If starting locally, copy `.env.example` to `.env` and edit
```bash
mv .env.example .env
vi .env
```
- If it is started by `docker-compose`, you can directly edit `docker-compose.env`, and use `docker compose up -d` directly after the modification to take effect
### About the use of environment variables with spaces
If your environment variable value contains spaces, in order for the system to recognize that this is a complete string instead of treating spaces as separators. You need to wrap a double quotes around the outside.
For example:
```bash
SMTP_SENDER="\"Tailchat\" example@163.com" # If there are repeated double quotes, they need to be escaped with an escape character
```
-------------
:::caution
Some environment variable modifications may need to clear the cache to take effect
:::
### How to clear the cache
Changes to some environment variables may involve cache updates, such as `FILE_LIMIT`, because config data needs to be sent to the client.
Therefore, it may appear that after modifying the environment variable, the performance on the client is still the same as before. At this point you need to clear the old cache for the update to take effect.
There are several options for clearing the cache:
- Execute `docker compose down` then run `docker compose up -d`. This is because the data of the `redis` service is not persisted, shutting down and restarting the service is equivalent to a brand new environment
- Manually enter the `redis` service to clean up the cache items whose name contains `config.client`, which contains the configuration items returned to the client
- Enter the cache management page of the `admin` management system. Click the `Clean Configuration Cache` button

45
website/docs/deployment/https-gateway.md Normal file
View File

@@ -0,0 +1,45 @@
---
sidebar_position: 8
title: Build https gateway (optional)
---
In `Tailchat`, some services are strongly dependent on `https`, such as audio and video calls, embedding external `https` media resources and web pages, etc.
At the same time, for the safety of users(client to server), we highly recommend that `Tailchat` be provided externally as `https` service.
![](/img/architecture/https-gateway.excalidraw.svg)
If you have no related experience, and only deploy `Tailchat` service on the same machine (without occupying **80**/**443** port), then we recommend `swag` from `Tailchat` Configuration begins.
:::info
You can see the original configuration in [Github](https://github.com/msgbyte/tailchat/tree/master/docker)
:::
Pull the required configuration file directly by the following command
```bash
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker/swag.yml
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker/swag.env.example -O swag.env
mkdir config
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker/config/nginx.conf -O ./config/nginx.conf
```
After completion, you should see the following three files in the current directory:
- `swag.yml`
- `swag.env`
- `config/nginx.conf`
Modify the content of `swag.env`, change the value of `URL` to the domain name, such as: `URL=tailchat.example.com`
:::info
The `https` protocol relies on the domain name for certificate verification, so it is necessary to assign a domain name in advance to point to the target server
:::
The address of the domain name needs to create an A pointing record in the management background of the purchased domain name.
After assigning the domain name we can start the service.
```bash
docker compose -f ./swag.yml up -d
```
If everything goes well, the `swag` service has automatically applied for a certificate for you and started the reverse proxy service. At this time, if you visit `https://tailchat.example.com` in the browser, you can see the familiar The interface is already there.

80
website/docs/deployment/install-docker.md Normal file
View File

@@ -0,0 +1,80 @@
---
sidebar_position: 2
title: Install the docker environment
---
> Because the `Tailchat` environment is a bit complicated for beginners, it provides a `docker-based one-command` environment configuration. But for students who are not familiar with `docker`, `docker` itself may also be a kind of complexity.
> Therefore, in order to facilitate everyone to quickly build `Tailchat`, this article is provided as a guide. Students who have a certain understanding of `docker` can skip this article
> This article takes `linux centos` as an example, the goal is to facilitate the deployment directly on the server. For students who want to use it on other systems (`windows`, `mac`), you can refer to the official documentation to install `docker`
## One-command installation of docker
Officially maintained one-command installation `Docker` script, suitable for students who don’t like to study details
Execute the following operations in sequence on the server terminal
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
If the installation is successful, you can skip the subsequent content.
## Manually install docker and docker compose
Official document: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
```bash
# If you have installed docker before, you can execute the following command to delete the old one
sudo yum remove docker \
docker-client \
docker-client-latest \
docker-common \
docker-latest \
docker-latest-logrotate \
docker-logrotate \
docker-engine
```
```bash
sudo yum install -y yum-utils # yum-utils provides the yum-config-manager command
sudo yum-config-manager \
--add-repo \
https://download.docker.com/linux/centos/docker-ce.repo
```
> Install docker and docker-compose plugins
```bash
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
```
*PS: `docker-compose-plugin` provides the `docker compose` command, the usage is the same as `docker-compose`*
> If `docker ps` shows that the daemon process is not started (Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?), you can execute the following command to start it: `sudo systemctl start docker`
## Install docker-compose separately
If the purchased server has been pre-installed with docker, if you want to install docker-compose separately, you can read this section:
Official document: [https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/)
```bash
curl -SL https://github.com/docker/compose/releases/download/v2.4.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose # Download binaries
sudo chmod +x /usr/local/bin/docker-compose # give execute permission
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose # Soft link to path, can be called directly
docker-compose --version # The line command returns the version number and the installation is successful
```
## NOTICE
For historical reasons, `docker compose` has a `docker` plugin version and a `docker compose` standalone version. Generally speaking, `docker compose xxx` is equivalent to `docker-compose xxx`
## Reference
- [Docker](https://docs.docker.com/engine/install/)
- [Docker Compose](https://docs.docker.com/compose/install/)

155
website/docs/deployment/mobile.md Normal file
View File

@@ -0,0 +1,155 @@
---
sidebar_position: 12
title: Mobile Self Compile (optional)
---
The source code of `Tailchat` mobile terminal is located in `client/mobile`. The technology stack is `react-native`
You can download the compiled general version directly from the official website: [https://tailchat.msgbyte.com/downloads](https://tailchat.msgbyte.com/downloads), or compile it yourself from the source code
This section mainly explains how to compile the mobile version of `Tailchat`.
## Prepare the development environment
You can see the complete development environment preparation operation at [https://reactnative.dev/docs/environment-setup](https://reactnative.dev/docs/environment-setup), so I won’t go into details here.
### Install dependencies
```bash
cd client/mobile
yarn
```
### Environment check
```bash
yarn doctor
```
## Prepare environment variables
```bash
cp.env.example.env
```
In the `.env` file we configure the required environment variables for compilation
```ini
TAILCHAT_UPLOAD_STORE_FILE=
TAILCHAT_UPLOAD_STORE_PASSWORD=
TAILCHAT_UPLOAD_KEY_ALIAS=
TAILCHAT_UPLOAD_KEY_PASSWORD=
GETUI_APPID=
GETUI_APPKEY=
GETUI_APPSECRET=
GETUI_HUAWEI_APP_ID=
```
## Certificate signing
If you are only using it for testing, you can skip this section and Tailchat will sign it for you using a public test certificate.
### Android
If you need to use your own certificate for signing, you need to fill in the following:
```ini
TAILCHAT_UPLOAD_STORE_FILE=
TAILCHAT_UPLOAD_STORE_PASSWORD=
TAILCHAT_UPLOAD_KEY_ALIAS=
TAILCHAT_UPLOAD_KEY_PASSWORD=
```
Need to fill in: certificate file name, password, alias, alias password
The certificate file needs to be placed in the `client/mobile/android/app` directory, usually a `*.keystore` file
> As for how to generate it, you can use `Android Studio` or `keytool` tool to generate it.
### iOS
TODO
## Push
`Tailchat` implements Android multi-vendor message push by integrating personal tweets as a relay
You can get all the required configuration in the application configuration of `getui`
Among them `GETUI_APPID`, `GETUI_APPKEY`, `GETUI_APPSECRET` are filled in in order
Corresponding configuration is required on the server side `GETUI_APPID`, `GETUI_APPKEY`, `GETUI_MASTERSECRET` so that the self-deployed push service can send push messages correctly
![](/img/misc/getui.png)
### Manufacturer Push
Manufacturer push can be turned on or off as needed
The source code needs to be modified as follows:
- `manifestPlaceholders` section and `dependencies` section of `client/mobile/android/app/build.gradle`
- `.env` environment variable configuration
## Compile
### Android
```bash
cd android
./gradlew assembleRelease
```
### iOS
iOS compilation needs to be done through `xcode`
> Screenshot cannot be taken due to lack of equipment, please follow the public information on the Internet.
### FAQ
If the following types of errors occur:
```
error Failed to install the app. Make sure you have the Android development environment set up: https://reactnative.dev/docs/environment-setup.
Error: Command failed: gradlew.bat app:installDebug -PreactNativeDevServerPort=8081
FAILURE: Build failed with an exception.
* What went wrong:
Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'.
> Could not resolve all dependencies for configuration ':app:debugRuntimeClasspath'.
> Could not create task ':app:generateDebugLintModel'.
> java.lang.NullPointerException (no error message)
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 27s
```
It may be because your environment variable is missing, you can leave the value empty, but the entry must exist
like:
```ini
GETUI_APPID=xxxxxxxxxxxx
GETUI_APPKEY=yyyyyyyyy
GETUI_APPSECRET=zzzzzzzzzz
GETUI_HUAWEI_APP_ID=
```
instead of
```ini
GETUI_APPID=xxxxxxxxxxxx
GETUI_APPKEY=yyyyyyyyy
GETUI_APPSECRET=zzzzzzzzzz
```
#### Can I compile it myself and publish it to the app store?
Yes, but please modify the application name, package name, icon and other information to prevent conflicts with official applications.

4
website/docs/deployment/other-way/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Install with other ways",
"position": 5
}

10
website/docs/deployment/other-way/bt.md Normal file
View File

@@ -0,0 +1,10 @@
---
sidebar_position: 3
title: Install with BT
---
:::info
This document is only available for Chinese.
:::
If you are chinese user, and wanna install Tailchat with bt, please learn more with switch language to chinese and read it.

4
website/docs/deployment/other-way/kubernetes/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Kubernetes",
"position": 2
}

147
website/docs/deployment/other-way/kubernetes/sealos.md Normal file
View File

@@ -0,0 +1,147 @@
---
sidebar_position: 2
title: Deployment in sealos
---
`Sealos` is an open-source Kubernetes deployment system that allows us to quickly create an on-demand, pay-as-you-go application cluster.
## First, enter Sealos and open "Application Management"
![](/img/kubernetes/sealos/1.png)
## Create a new application
![](/img/kubernetes/sealos/2.png)
### Create dependencies
As an enterprise-level application, `tailchat` has the minimum dependencies of `mongodb`, `redis`, and `minio`. Let's create them one by one.
#### MongoDB
For convenience, we will fix one instance and bind it to local storage. The image used is `mongo:4`. Note that because we did not set a password for the database, do not provide network services to the public network. The container exposes port 27017, which is the default database service port. The content is as follows:
![](/img/kubernetes/sealos/3.png)
Click "Deploy Application" to submit the deployment. Wait patiently for a while, and you can see that the application has started up.
![](/img/kubernetes/sealos/4.png)
> Note: that the initial allocation of 64m is too small for MongoDB, so I changed it to 128m by modifying the application. Resource allocation can be changed at any time, which is also a convenient feature of Sealos/Kubernetes.
#### Minio
Next, we will create Minio, an open-source object storage service. We can also quickly create it through Sealos's UI. The image used is `minio/minio`. Note that we need to make some adjustments:
- Expose port: 9000
- Change the run command to: `minio`
- Change the command parameters to: `server /data`
- Set environment variables:
- MINIO_ROOT_USER: tailchat
- MINIO_ROOT_PASSWORD: com.msgbyte.tailchat
- Local storage: `/data`
The final result is as follows:
![](/img/kubernetes/sealos/5.png)
Click the "Deploy" button and you can see that the service has started up normally.
#### Redis
Finally, we need to deploy Redis as a content cache and message forwarding. The image used is `redis:alpine`, and the exposed port is `6379`. The final result is as follows:
![](/img/kubernetes/sealos/6.png)
### Create Tailchat itself
At this point, all the dependencies required by Tailchat have been deployed, as shown below:
![](/img/kubernetes/sealos/7.png)
Now we can deploy the Tailchat itself. The Tailchat itself will be relatively complex, but because Sealos is purely UI-based, it will not be too complicated.
- Use image: `moonrailgun/tailchat`
- Expose port: `11000` (remember to open external access)
- Configure environment variables as follows:
```
SERVICEDIR=services,plugins
TRANSPORTER=redis://redis:6379
REDIS_URL=redis://redis:6379
MONGO_URL=mongodb://mongo/tailchat
MINIO_URL=minio:9000
MINIO_USER=tailchat
MINIO_PASS=com.msgbyte.tailchat
```
The final effect is as follows:
![](/img/kubernetes/sealos/8.png)
After waiting patiently for a while, you can see that the Tailchat service has started up.
![](/img/kubernetes/sealos/9.png)
## Preview service
First, we can check the availability of the Tailchat service by adding `/health` to the external address provided by the service, such as `https://<xxxxxxxxxx>.cloud.sealos.io/health`. When it starts up, the Tailchat service will return content like this:
![](/img/kubernetes/sealos/10.png)
This JSON string contains the image version used, node name, system usage, and microservice loading status. Here we can see that my common services, such as `user`/`chat.message`, and some services with plugin prefixes such as `plugin.registry`, have all started up normally, indicating that our server is running normally. Now we can directly access our external address and see that after a short loading time, the page opens normally and automatically jumps to the login page.
![](/img/kubernetes/sealos/11.png)
Register an account casually, and you can see that we can enter the main interface of Tailchat normally, as shown in the following figure:
![](/img/kubernetes/sealos/12.png)
At this point, our service has successfully landed in Sealos.
## Scaling service
Of course, as a distributed architecture system, Tailchat naturally supports horizontal scaling. In Sealos, scaling is also very simple. Just modify the number of instances through the change operation:
![](/img/kubernetes/sealos/13.png)
![](/img/kubernetes/sealos/14.png)
![](/img/kubernetes/sealos/15.png)
At this point, when we access `https://<xxxxxxxxxx>.cloud.sealos.io/health`, we can see that we can access different nodes.
![](/img/kubernetes/sealos/16.png)
## Add Tailchat entry to desktop
Open Terminal, enter `vim app.yml` to create and edit a configuration file
Enter the following content, note that the url should be replaced with the url deployed by yourself
```yml
apiVersion: app.sealos.io/v1
kind: App
metadata:
name: tailchat-app-entry
spec:
name: Tailchat
icon:
type: iframe
data:
url: <Your url>
desc:
icon: https://tailchat.msgbyte.com/img/logo.svg
menuData:
nameColor: text-black
helpDropDown:
helpDocs:
displayType: normal
```
Press `esc` to exit edit mode, press `:wq` to save and exit vim
Type `kubectl apply -f app.yml` to start the configuration.
After refreshing the page, we can see that our entry appears on the desktop of `sealos`
![](/img/kubernetes/sealos/17.png)

117
website/docs/deployment/other-way/kubernetes/simple.md Normal file
View File

@@ -0,0 +1,117 @@
---
sidebar_position: 1
title: Simple Deployment
---
## Introduction
Kubernetes is an open-source container orchestration platform used for automating the deployment, scaling, and management of containerized applications. It provides a way to orchestrate containers, automating tasks such as deployment, scheduling, load balancing, and fault recovery, making containerized applications run efficiently in a distributed system.
Advantages of Kubernetes include:
- Automation: Kubernetes automates tasks such as deployment, scheduling, load balancing, and fault recovery, reducing the amount of manual work required.
- Scalability: Kubernetes can manage thousands of containerized applications in large-scale clusters, with good horizontal and vertical scalability.
- Flexibility: Kubernetes supports multiple container runtimes and multiple cloud platforms, allowing applications to be deployed and managed in different environments.
- Reliability: Kubernetes provides powerful fault recovery mechanisms and self-healing capabilities, ensuring high availability and reliability of applications.
- Community support: Kubernetes is an active open-source project with a large community support and ecosystem, allowing for quick updates and support.
## Quick Start
If you want to deploy the Tailchat project on Kubernetes, you can find the prepared simple Tailchat deployment configuration in the `docker/simple/k8s` subdirectory of the project directory. These configuration files include Kubernetes resource definitions for running Tailchat, such as StatefulSet, Service, and dependencies such as databases and persistent storage. These resource definitions allow you to quickly deploy a simple Tailchat project on Kubernetes without manually creating and configuring these resources.
:::info
Note that the deployed Tailchat in this tutorial does not include the complete Tailchat ecosystem, such as the **Open Platform** and **Admin Management Platform**.
:::
### Environment Dependencies
To start this chapter, we assume that you have a working Kubernetes environment ready. This section does not describe how to set up a k8s environment.
### Getting Started
First, we need to clone the project repository:
```bash
git clone git@github.com:msgbyte/tailchat.git
```
Change the working directory to the configuration file directory:
```bash
cd docker/simple/k8s
```
At this point, you can see many prepared configuration files, and we can start by running a single command:
```bash
kubectl apply -f namespace.yml -f pv.yml -f mongo.yml -f minio.yml -f redis.yml -f tailchat.yml
```
This command will create the `namespace`, create `pv` and `pvc`, create `mongodb`, `minio`, `redis`, and other necessary third-party middleware, and finally start a multi-instance `tailchat` service.
You can check the status of each service using the following command:
```bash
kubectl get svc -n tailchat
```
### Routing and Load Balancing
When all services are ready, our Tailchat service is now running in the cluster, but we cannot access it because it has not been exposed to the outside.
For local testing, we can use the `port forward` function to map the port of a pod to the local machine. In a production environment, however, we need to build routing and forwarding.
Taking `traefik` as an example:
> Traefik is an open-source reverse proxy and load balancer designed specifically for routing and load balancing traffic in containerized applications and microservices architectures. Traefik supports multiple backend services, including Docker, Kubernetes, Mesos, Swarm, Consul, Etcd, and more. It can automatically discover and configure backend services and route traffic to the corresponding service instances based on rules.
#### Installing Helm and Adding Repository Address
The installation of `helm` is not discussed here. We execute the following command to add `traefik` to the repository list:
```bash
helm repo add traefik https://helm.traefik.io/traefik
```
#### Installing Traefik in the Tailchat Namespace
```bash
helm install traefik traefik/traefik -n tailchat
```
#### Starting Ingress Resource Declaration
```bash
kubectl apply -f ingress.yml
```
If everything is ok, you can see the following output using the following command:
```bash
kubectl get services -n tailchat
```
![](/img/kubernetes/traefik-svc.png)
#### Setting up DNS Services
You can modify the domain address configuration in the `ingress.yml` mentioned above, which defaults to `http://tailchat.internal.com/`.
If you do not wish to modify or do not have a domain name, you can modify the `hosts` file to achieve this:
```bash
sudo vim /etc/hosts
```
Then add the following path:
```
127.0.0.1 tailchat.internal.com
```
Now you can open your browser and visit `http://tailchat.internal.com` to access the Tailchat service deployed on Kubernetes.
Of course, you can also check the availability of the service by visiting the following address:
```
http://tailchat.internal.com/health
```

87
website/docs/deployment/other-way/manual.md Normal file
View File

@@ -0,0 +1,87 @@
---
sidebar_position: 1
title: Manual Deployment
---
:::caution
The content of this chapter requires you to have a certain degree of understanding of nodejs, git, linux. When there are problems such as dependency problems, environmental problems, system problems, etc., you need to have the ability to solve and troubleshoot problems by yourself.
If you do not understand this, it is not recommended that you use the contents of this chapter for deployment. It is recommended to use a unified image for deployment.
:::
## Dependencies
- git
- nodejs v16.18.0 or above
- pnpm v8.3.1 or above
- mongodb
- redis
- minio
## Download the source code
```bash
mkdir msgbyte && cd msgbyte
git clone https://github.com/msgbyte/tailchat.git
```
### Switch to stable code
Because the cloned code is the latest code, it may be unstable for a short period of time, so if you want to switch to the stable code of each version, you can use the tag function of git
For example, if you wanna use `v1.7.6`, you can use the command:
```bash
git checkout v1.7.6
```
## Compile the project
Tailchat is a front-end and back-end separated project. So we have to deal with the front-end code and the back-end code separately
### Install dependencies
We assume you have installed `nodejs v16.18.0+` or above. And installed `pnpm v8.3.1` or above
```bash
cd tailchat
pnpm install
```
This command will take some time to install all the dependencies of Tailchat. When the installation is complete, the internal plug-in will automatically execute the compilation command.
### Building the project
```bash
NODE_ENV=production pnpm build
```
This command will execute the commands for compiling the front-end and back-end management terminals in parallel. And move the front-end product to the `server/dist/public` directory of the server
When the project is built, our product can run normally
:::caution
Please build in `macos` / `linux` environment as much as possible, window does not necessarily fully support shell commands
:::
## Run the project
In order to ensure the horizontal expansion of the project, although the core code of `Tailchat` is written in the same project, it can be divided into multiple subdivided microservices when it is actually started. Selectively enable different services by passing in a combination of different environment variables.
Create an environment variable file in the server directory using the `.env.example` directory as an example
```bash
cp server/.env.example server/dist/.env
vim .env
```
Modify the necessary environment variables to your own, such as `MONGO_URL`, `REDIS_URL`, `MINIO_URL`
then start the service
```bash
SERVICEDIR=services,plugins pnpm start:service
```
> `SERVICEDIR` indicates the directory where the microservice is loaded

26
website/docs/deployment/quickstart.md Normal file
View File

@@ -0,0 +1,26 @@
---
sidebar_position: 1
title: Quick Start
---
## Demo environment
The demo environment will continuously deploy the latest front-end code and update the back-end code from time to time
[https://nightly.paw.msgbyte.com/](https://nightly.paw.msgbyte.com/)
## Deployment method
### Docker/Docker Compose
It is highly recommended to use `docker-compose` to deploy `tailchat`
Please refer to the tutorial: [Docker Compose Deployment](./docker-compose.mdx)
### Kubernetes
Please refer to the tutorial: [Kubernetes Simple Deployment](./other-way/kubernetes/simple.md)
## System Structure
See [System Architecture](../architecture.md)

46
website/docs/deployment/smtp.md Normal file
View File

@@ -0,0 +1,46 @@
---
sidebar_position: 10
title: SMTP Service (optional)
---
`Tailchat` includes email services, used in scenarios such as **password recovery**, **mail authentication**
Only simple mail service (SMTP) is used in `Tailchat` because only one-way sending mail is required and no receiving mail is required.
In order to enable the service, we need to set the following in the environment variable:
- `SMTP_SENDER`: sender information, the general format is `xxx@example.com` or `"YourName" xxx@example.com`
- `SMTP_URI`: SMTP mail service address, follow the international common URI format: `<protocol>://<username>:<password>@<host>:<port>/<other-info>`
## Auxiliary testing using cli
If you are not familiar with SMTP service, in order to improve detection efficiency, you can choose to use `tailchat-cli` to quickly help you verify the reliability of SMTP service
> For usage of tailchat-cli, see [tailchat-cli](../cli/tailchat-cli.md)
```
tailchat smtp
SMTP Service
Commands:
tailchat smtp verify Verify smtp sender service
tailchat smtp test Send test email with smtp service
Options:
--version Show version number [boolean]
-h, --help Show help [boolean]
```
You can verify URI availability with `tailchat smtp verify`, no email is actually sent during this operation. Similar to account login
If there are still problems after the verification is passed, you can use `tailchat smtp test` to actually send a test email to help you troubleshoot the problem, because there are many possibilities in the actual production environment, such as bounced letters caused by audit problems of various service providers, such as The degree of verification is different. For example, some service providers allow custom sender names, and some have strict requirements on them.
## SMTP_URI example
Because the services provided by different service providers are different, only some of the content can be cited here for demonstration. If you have other URIs that can be used as examples, please submit a PR to help us improve the documentation together:
- `smtps://<username>:<password>@smtp.exmail.qq.com/?pool=true`
- `smtps://<username>:<password>@smtp.163.com/?pool=true`
- `smtps://<qqNumber>:<password>@smtp.qq.com/?pool=true`

103
website/docs/deployment/troubleshooting.md Normal file
View File

@@ -0,0 +1,103 @@
---
sidebar_position: 50
title: Troubleshooting
---
## Deployment related
### How to update the version?
It is the same as getting the image when deploying
```bash
docker pull moonrailgun/tailchat
docker tag moonrailgun/tailchat tailchat
```
Then restart the application, such as `docker compose up -d`
### How to use the specified version?
```bash
docker pull moonrailgun/tailchat:1.8.4
docker tag moonrailgun/tailchat:1.8.4 tailchat
```
Just specify the version number when pulling the image
## Server related
### The Websocket connection access is incorrect, the manifestation is that it can be registered but the main interface cannot be opened
If nginx is used for reverse proxy. Please ensure that the configuration of nginx supports websocket, a reference configuration is as follows:
```
server {
server_name demo.example.com;
listen 443 ssl;
access_log /var/log/nginx/host.access.log main;
location / {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-real-ip $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_redirect off;
proxy_pass http://127.0.0.1:11000/;
}
}
```
### Internal Network can be accessed but External Network can not be accessed?
You can start a simple http service to see if it is a problem with the docker-proxy layer. *This problem may occur on the docker-ce image machine of Tencent lighthouse, you can choose to use the centos7 image to reinstall*
```bash
docker run --rm --name nginx-test -p 8080:80 nginx
```
### There will be a random hash volume at startup
See: [https://github.com/msgbyte/tailchat/issues/79](https://github.com/msgbyte/tailchat/issues/79)
### Getting `502 Invalid paramenters` when sending mail
If the prompt is similar to: `Error: Mail command failed: 502 Invalid paramenters`
```
code:'EENVELOPE',
response: '502 Invalid paramenters',
responseCode: 502,
command: 'MAIL FROM'
```
Please check whether your `SMTP_SENDER` content is correct, the general format is `xxx@example.com` or `"YourName" xxx@example.com`
### Openapi service is always restart
If this throw error `Issuer Identifier must be a valid web uri`
you should make sure has been writing a url(`http://xxxx` or `https://xxxx`) in env `API_URL`
## Openapi platform related
If the open platform is deployed behind a proxy, if the endpoint in the JSON of the access `/open/.well-known/openid-configuration` result is incorrect, please try to modify the configuration of the proxy to forward real ip.
Such as nginx:
```
location / {
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;
proxy_pass http://127.0.0.1:11000;
proxy_redirect off;
}
```

4
website/docs/devops/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Operations",
"position": 15
}

22
website/docs/devops/mongodb.md Normal file
View File

@@ -0,0 +1,22 @@
---
sidebar_position: 1
title: Database management
---
`Tailchat` uses mongodb as the main database to store user information
In `docker`, common operation and maintenance commands are as follows:
```bash
# backup
docker exec -i <IMAGE_NAME> mongodump -d tailchat --archive > ./backup.archive
# restore
docker exec -i <IMAGE_NAME> mongorestore -d tailchat --archive < ./backup.archive
```
Among them `<IMAGE_NAME>` represents the name of the mongodb image, and `-d tailchat` represents the name of the database used, the default database name is `tailchat`, you can modify it through the environment variable `MONGO_URL`
:::info
For user data security, it is recommended to create a scheduled task to regularly back up the database file
:::

90
website/docs/intro.md Normal file
View File

@@ -0,0 +1,90 @@
---
sidebar_position: 1
title: Summary
---
`Tailchat` is an open source IM application that is pluggable and easy to expand. Plugin architecture gives `Tailchat` unlimited possibilities.
Front-end micro-kernel architecture + back-end micro-service architecture makes `Tailchat` to control any customized/privatized scenarios
Created for enterprises and private domain users, highly free group management and customized panel display allow private domain owners to better display their works, manage users, and build their own brand and circle.
## Feature
- Complete basic ability of instant messaging
- The free expansion ability endowed by the plugin architecture
- The horizontal expansion capability endowed by the microservice architecture
## Highlight
- The front-end micro-kernel architecture based on [mini-star](https://ministar.moonrailgun.com/) and the back-end micro-service architecture based on [moleculer](https://moleculer.services/) can adapt to various user usage, easy to expand
- A complete chat system that supports various syntaxes such as mentions, panel jumps, rich text, markdown, url links, etc.
- Message reaction mechanism, allowing you to express yourself through expressions
- File sharing and image sending
- Support voice calls and video calls
- Perfect identity group management, RBAC
- User Management and User Muting
- Email authentication and password retrieval
- Various panels: web page embedding, custom html, topic panel
- Simple message push and github notification subscription
- Admin platform
- Openapi platform
- Bot
- OAuth
- More wonderful chemical reactions brought by plugins
- custom theme
- listen to music online
- message encryption
- fetch link metadata
- Airdrop
- Task
- Draw
- Font size
- Toolbox
- ...
## Technology Stack
- Frontend
- `React`
- `Redux`
- `mini-star`
- `tailwindcss`
- `iconify`
- Backend
- `Nodejs`
- `Socket.io`
- `koa`
- `moleculer`
## Screenshot
#### Overview
![](/img/intro/hello.png)
#### Plugin Center
![](/img/intro/plugins.png)
#### Themes
![](/img/intro/theme.png)
#### Roles & Permission
![](/img/intro/roles.png)
#### Github Subscription Bot
![](/img/intro/github-bot.png)
#### Admin
![](/img/intro/admin-network.png)
## Open Source Agreement
For open source agreements, please mainly refer to the following documents:
[Apache 2.0](https://github.com/msgbyte/tailchat/blob/master/LICENSE)

4
website/docs/meeting/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Video Conference",
"position": 35
}

98
website/docs/meeting/agora.md Normal file
View File

@@ -0,0 +1,98 @@
---
sidebar_position: 10
title: Agora Plugin Deployment Guide
---
:::info
The agora plugin needs to ensure that your `tailchat` image version is 1.4.0+
:::
## Apply for projects on the agora platform
The Tailchat agora integration is an audio and video call function that relies on the agora service, so it needs to be registered on the agora platform before use.
Agora website: [https://www.agora.io/](https://www.agora.io/)
### Get configuration parameters
After registration/login, it will automatically jump to the console. Project configuration can be done in the console
![](./images/1.png)
If you have not created a project, you need to create a project first. As shown below
![](./images/2.png)
It is recommended to use safe mode to avoid being stolen by others.
Next we need to get some configuration items to configure the Tailchat's agora plugin.
![](./images/3.png)
In project configuration we can get `appid` and `app cert`. These two are the environment variables `AGORA_APP_ID` and `AGORA_APP_CERT` that we will use later
### Get client credentials
In addition, we also need to obtain the customer's permission at the `RESTful API` in the upper right corner,
The operation is as shown in the figure:
![](./images/4.png)
![](./images/5.png)
In this way we get two other environment variables: `AGORA_CUSTOMER_KEY` and `AGORA_CUSTOMER_SECRET`.
Our initial preparations are complete
## Install plugin
At present, the server-side plugin of the Agora plugin has been installed by default, and you do not need to do anything. However, environment variables need to be configured for use.
### Configure environment variables
To configure environment variables, see [environment variables](../deployment/environment.md)
The agora plugin requires environment variables as follows:
- `AGORA_APP_ID`: the application id of the Agora project
- `AGORA_APP_CERT`: AGORA project certificate
- `AGORA_CUSTOMER_KEY`: AGORA customer id
- `AGORA_CUSTOMER_SECRET`: AGORA customer secret key
These environment variables can be obtained in the above tutorial.
After configuring the environment variables, every will be final
## Application service status callback
:::info
you can skip it if you dont need it.
:::
In order to synchronize the call status to `Tailchat`, it is necessary to apply for a server callback in Agora.
In project configuration, we need to enable `Notification Center Service Configuration` in `Service Config`
![](./images/6.png)
Need to subscribe to the following events:
- channel create=101
- channel destroy=102
- broadcaster join channel=103
- broadcaster leave channel=104
The receiving server URL is generally: `https://<YOUR SERVER DOMAIN>/api/plugin:com.msgbyte.agora/webhook`, where `<YOUR SERVER DOMAIN>` is replaced with your `Tailchat` domain name.
:::info
The service of Agora will check the connectivity of the server, so it is necessary to configure the environment variables and start the service before performing this step.
In addition, the Agora needs to configure `https` and `webrtc` service also depends on `https`, so you need to ensure that the server gateway supports the `https` protocol
:::
After the configuration is complete, you will see the following prompt. It will take effect after the confirmation of the staff of the agora.
![](./images/7.png)

100
website/docs/meeting/deployment.md Normal file
View File

@@ -0,0 +1,100 @@
---
sidebar_position: 2
title: Deploy Tailchat Meeting
---
:::info
The `Tailchat Meeting` solution is currently not integrated with `Tailchat`, if you want to use the video conferencing solution in Tailchat, please choose `agora` or `livekit` solution
:::
The video conferencing service `Tailchat Meeting` can exist as an independent application. In this section, we will describe how to deploy `Tailchat Meeting` independently
The following content is based on the `docker` environment, please ensure that the server has the most basic `docker` environment.
If you haven't installed `docker` + `docker-compose`, you can check the document [Install docker environment](../deployment/install-docker.md)
## Fast deployment
```bash
git clone https://github.com/msgbyte/tailchat-meeting --depth=1
```
> NOTE: Next, the host mode of docker will be used for installation. That means, `docker-compose` will automatically bind the host port
The ports that need to be reserved by the server are as follows:
- swag (server gateway, nginx enhanced version, the port can be modified through the configuration file tailchat-meeting/compose/nginx.conf)
- 80
- 443
- tailchat-meeting
- 13001
- 40000-49999 (for RTC service, dynamic occupancy)
-redis
- 6379
**The above ports will be exposed on the host machine. For the sake of server security, it is recommended to configure a suitable firewall policy, and only expose the necessary ports 443 and 40000-49999**
```bash
cd tailchat-meeting/compose
cp docker-compose.env.example docker-compose.env
vi docker-compose.env
```
Modify environment variables.
The environment variables are as follows:
```
# Internal IP
MEDIASOUP_IP=
# Public IP
MEDIASOUP_ANNOUNCED_IP=
# swag
URL=
SUBDOMAINS=
TZ=Asia/Shanghai
```
其中
- If you only deploy on a single machine, `MEDIASOUP_IP` and `MEDIASOUP_ANNOUNCED_IP` can both fill in the public network ip of the server, **But for service providers with flexible deployment networks (such as domestic AWS, Tencent Cloud, Alibaba Cloud, etc.) must strictly follow the notes to fill in the internal IP and public network IP** (because the external network IP provided by this type of service provider is not bound to the network card)
- `tailchat-meeting` is based on **webrtc** service, so it strongly depends on https/wss protocol. The swag service can automatically apply for an https certificate for you, but you must assign a valid domain name and ensure that the dns point has been pointed to the server.
- More related documents can be viewed [README](https://github.com/linuxserver/docker-letsencrypt/blob/master/README.md)
- Sample configuration:
```bash
URL=meeting.example.com # 这里请填入
SUBDOMAINS= # 该参数用于多域名证书申请，可留空
```
After the modification, you can directly execute the following command
```bash
docker compose up -d
```
`docker compose` will automatically download images from the network and build `tailchat-meeting`
Building may take time and resources. Especially for building the frontend code, please be patient if you use a server with a low server.
> In the real world test, the time-consuming reference of a small resource server with 1 core and 2G is as follows:
> - Download dependencies: 3 minutes
> - Compile frontend code: 5 minutes
Visit `https://meeting.example.com` to see `tailchat-meeting` page
## Combined usage
For fool-proof deployment, it only needs one command to execute. If there are ready-made gateway services (such as nginx, caddy, etc.) and redis instances, you can selectively start the services.
For example:
```bash
docker compose up tailchat-meeting -d # Only run the tailchat-meeting instance
```
## Reasons for using host mode
The core RTC service of `tailchat-meeting` needs to apply for a port at runtime, but this function cannot be realized for docker. Pre-applying for a certain range of port bindings will not only waste meaningless ports, but also occupy a lot of resources and kill the system instantly when starting.
**It should be noted that please do not expose the 6379 port where redis is located, which may cause security risks. **

BIN
website/docs/meeting/images/1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 128 KiB

BIN
website/docs/meeting/images/2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 214 KiB

BIN
website/docs/meeting/images/3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 94 KiB

BIN
website/docs/meeting/images/4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
website/docs/meeting/images/5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

BIN
website/docs/meeting/images/6.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 296 KiB

BIN
website/docs/meeting/images/7.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 138 KiB

47
website/docs/meeting/intro.md Normal file
View File

@@ -0,0 +1,47 @@
---
sidebar_position: 1
title: Summary
---
:::info
Video Conference solutions require SSL support, so only websites that support https will work properly
:::
`Tailchat` provides those solutions for video and voice calls, you can choose according to the actual situation:
- ~~`tailchat-meeting` self-deploying video conferencing (WIP)~~
- `agora` Acoustic Network integration, for details, see: [Acoustic Network Plug-in Deployment Guide](./agora.md)
- `livekit` Allow self-host solution: [Livekit Plugin Deployment Guide](./livekit.md)
<details>
<summary>Collapsed content is outdated</summary>
## Tailchat Meeting
The video conferencing module is an important part of the suite of `Tailchat` series. Capabilities are provided as follows:
- Voice communication
- Video session
- screen sharing
- virtual background
- file transfer
- chat record
At the same time, `tailchat-meeting` can also exist as an independent product, and you can quickly initiate/join meetings without logging in
### Project repository
- Open source address: [https://github.com/msgbyte/tailchat-meeting](https://github.com/msgbyte/tailchat-meeting)
- Open source agreement: Apache 2.0
:::info Open source statement
This project is based on secondary development of [edumeet](https://github.com/edumeet/edumeet) and [mediasoup](https://github.com/versatica/mediasoup).
On this basis, function addition, SDK implementation and code optimization were carried out. If you want to find a looser implementation of the open source protocol (MIT + ISC protocol), you can take a look at these two projects
:::
### Project Architecture
![](/img/architecture/meeting.excalidraw.svg)
</details>

73
website/docs/meeting/livekit.md Normal file
View File

@@ -0,0 +1,73 @@
---
sidebar_position: 20
title: Livekit Plugin Deployment Guide
---
`Livekit` is an open source video conferencing solution based on the `Apache-2.0` open source protocol, allowing self-host, supporting video conferencing, live streaming, recording and other scenarios
You can use his cloud service or self-host. Below I will introduce how to integrate `Livekit` into `Tailchat`:
## Cloud Services
First enter the Livekit cloud platform: [https://cloud.livekit.io/](https://cloud.livekit.io/), in the first time you enter, you need to create a project:
It will ask some questions, just answer them according to the situation.
![](/img/advanced-usage/livekit/1.png)
After completion, we will enter the console main dashboard:
![](/img/advanced-usage/livekit/2.png)
### Get the required environment variables
For the plugin to work, we need the following environment variables:
- `LIVEKIT_URL`
- `LIVEKIT_API_KEY`
- `LIVEKIT_API_SECRET`
Among them, `LIVEKIT_URL` can be obtained directly from the console, in the form of `wss://********.livekit.cloud`
In the `Settings` menu on the left, we need to create a pair of secret keys by ourselves
![](/img/advanced-usage/livekit/3.png)
![](/img/advanced-usage/livekit/4.png)
![](/img/advanced-usage/livekit/5.png)
Here we can get `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`.
Record and fill in the environment variables and start `Tailchat`.
### Start the webhook
![](/img/advanced-usage/livekit/6.png)
If you need the above-mentioned channel online prompts to be updated immediately, you need to start a `webhook-receiver` separately to accept pushes from `livekit` and forward the received events to `Tailchat`, so that `Tailchat` can update all groups Display of group membership.
The official `docker-compose` configuration has been prepared for you with one click, just like `admin`:
```bash
wget https://raw.githubusercontent.com/msgbyte/tailchat/master/docker/livekit.yml
docker compose -f docker-compose.yml -f livekit.yml up -d
```
At this point you can see a `tailchat-livekit-webhook-receiver` service in the docker running container.
Then we switch to the `livekit` console and add our address in the `webhook`.
![](/img/advanced-usage/livekit/7.png)
Generally `https://<your tailchat url>/livekit/webhook`, remember to choose the same key pair as the service
![](/img/advanced-usage/livekit/8.png)
> PS: There may be some delays in cloud applications.
## Self-host
See the official documentation for self-host: [https://docs.livekit.io/oss/deployment/](https://docs.livekit.io/oss/deployment/)
In addition to the different deployment methods and configuration first, others are the same as using cloud services

11
website/docs/nightly-env.md Normal file
View File

@@ -0,0 +1,11 @@
---
sidebar_position: 100
title: Demo Environment and Groups
---
The demonstration environment is to reflect the performance of `Tailchat` on a low-configuration server (less resource occupation is the key requirement of Tailchat). The server in the test environment is 1C2G1M (1 cpu core, 2g memory space, 1mb bandwidth limit).
Also, here are some groups for demonstrating Tailchat functionality:
- [Tailchat Nightly](https://nightly.paw.msgbyte.com/invite/8Jfm1dWb)
- [Genshin](https://nightly.paw.msgbyte.com/invite/GFFzfD5H)

4
website/docs/plugin-list/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Plugin List",
"position": 20
}

220
website/docs/plugin-list/fe.md Normal file
View File

@@ -0,0 +1,220 @@
---
sidebar_position: 1
title: Pure Frontend Plugin (27)
---
### com.msgbyte.ai-assistant AI Assistant
Add chatgpt into Tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.ai-assistant)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.ai-assistant/manifest.json)
### com.msgbyte.bbcode BBCode Mmessage Interpreter
A plugin for supporting bbcode syntax to interpret rich text messages
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.bbcode)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.bbcode/manifest.json)
### com.msgbyte.biggerfont Bigger Font Size
Add the feature of enlarging the font size to Tailchat, which is convenient for different user
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.biggerfont)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.biggerfont/manifest.json)
### com.msgbyte.draw Drawing plugin
Allows sending custom drawings
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.draw)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.draw/manifest.json)
### com.msgbyte.env.electron Electron Support
Add support for Electron environment in Tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.env.electron)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.env.electron/manifest.json)
### com.msgbyte.env.rn React Native Support
Add support for ReactNative environment in Tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.env.rn)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.env.rn/manifest.json)
### com.msgbyte.filepizza file.pizza
Quickly open filepizza in the chat input box to support p2p file transfer
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.filepizza)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.filepizza/manifest.json)
### com.msgbyte.filesend filesend
Quickly open Filesend in the chat input box to support file transfer
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.filesend)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.filesend/manifest.json)
### com.msgbyte.filesfm files.fm
Quickly open files.fm in the chat input box to support file transfer
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.filesfm)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.filesfm/manifest.json)
### com.msgbyte.genshin Genshin Toolbox
Add Genshin-related entertainment capabilities to Tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.genshin)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.genshin/manifest.json)
### com.msgbyte.integration third party integration
Used to integrate third-party applications in groups
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.integration)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.integration/manifest.json)
### com.msgbyte.intro Intro plugin
Turn on the ability to introduce the app for the first time for the app
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.intro)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.intro/manifest.json)
### com.msgbyte.mdpanel Markdown Panel
Add markdown panel support
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.mdpanel)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.mdpanel/manifest.json)
### com.msgbyte.miaolang Miaolang
It is allowed to send meow, and the two parties encrypt the conversation after installing the plugin. People who have not installed the plugin will see 'meow'
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.miaolang)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.miaolang/manifest.json)
### com.msgbyte.music Listen Music Online
Provide online music listening service, the content comes from the Internet
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.music)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.music/manifest.json)
### com.msgbyte.notify Message notification plugin
Ability to add notifications to apps
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.notify)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.notify/manifest.json)
### com.msgbyte.offline-icons Offline Icons
Add prefetched icons which need run in intranet environment
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.offline-icons)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.offline-icons/manifest.json)
### com.msgbyte.openapi Openapi Platform Plugin
Provide the operating capability of the open platform for the application
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.openapi)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.openapi/manifest.json)
### com.msgbyte.posthog Posthog
Posthog Statistics
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.posthog)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.posthog/manifest.json)
### com.msgbyte.sentry Sentry
Sentry error handling
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.sentry)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.sentry/manifest.json)
### com.msgbyte.snapdrop Snapdrop
Snapdrop —— Send files and messages on the same network
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.snapdrop)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.snapdrop/manifest.json)
### com.msgbyte.toolwa Tool frog!
Tool frog —— online tools
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.toolwa)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.toolwa/manifest.json)
### com.msgbyte.user.location User Location
Add geographic location records for user information
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.user.location)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.user.location/manifest.json)
### com.msgbyte.webview Web Panel Plugin
Provides groups with the ability to create web panels
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.webview)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.webview/manifest.json)
### com.msgbyte.wenshushu wenshushu
Quickly open Wenshushu in the chat input box to support file transfer
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.wenshushu)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.wenshushu/manifest.json)
### com.msgbyte.widget.sakana sakana-widget
Add sakana widget in tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.widget.sakana)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.widget.sakana/manifest.json)
### com.msgbyte.wormhole wormhole
Quickly open wormhole in the chat input box to support file transfer
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.wormhole)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.wormhole/manifest.json)

100
website/docs/plugin-list/full.md Normal file
View File

@@ -0,0 +1,100 @@
---
sidebar_position: 3
title: Backend plugins (12)
---
### com.msgbyte.agora Agora
Add the Agora audio and video communication feature to Tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.agora/web/plugins/com.msgbyte.agora)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.agora/web/plugins/com.msgbyte.agora/manifest.json)
### com.msgbyte.discover Discover
Add Discover panel which can help user found groups
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.discover/web/plugins/com.msgbyte.discover)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.discover/web/plugins/com.msgbyte.discover/manifest.json)
### com.msgbyte.github Github Subscription
Subscribe to the Github project dynamics to the group
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.github/web/plugins/com.msgbyte.github)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.github/web/plugins/com.msgbyte.github/manifest.json)
### com.msgbyte.iam Identity and Access Management
Provide Tailchat with the function of conveniently accessing external account systems
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.iam/web/plugins/com.msgbyte.iam)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.iam/web/plugins/com.msgbyte.iam/manifest.json)
### com.msgbyte.linkmeta Url metadata display
Parse and get the overview of url information in the chat information, such as title/overview/thumbnail, support media path, directly display media player (specially support bilibili, automatically load the iframe player of bilibili)
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.linkmeta/web/plugins/com.msgbyte.linkmeta)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.linkmeta/web/plugins/com.msgbyte.linkmeta/manifest.json)
### com.msgbyte.livekit livekit
Add livekit to provide meeting and live streaming feature
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.livekit/web/plugins/com.msgbyte.livekit)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.livekit/web/plugins/com.msgbyte.livekit/manifest.json)
### com.msgbyte.meeting Audio and video service (WIP)
Provide audio and video communication services for Tailchat
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.meeting/web/plugins/com.msgbyte.meeting)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.meeting/web/plugins/com.msgbyte.meeting/manifest.json)
### com.msgbyte.simplenotify Simple Notify Bot
A simple generic notification bot for sending messages directly to groups
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.simplenotify/web/plugins/com.msgbyte.simplenotify)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.simplenotify/web/plugins/com.msgbyte.simplenotify/manifest.json)
### com.msgbyte.tasks Task Manage
Task management plugin, add TODO panel in personal panel for personal todo management
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.tasks/web/plugins/com.msgbyte.tasks)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.tasks/web/plugins/com.msgbyte.tasks/manifest.json)
### com.msgbyte.topic Topic
Provide topic feature for groups
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.topic/web/plugins/com.msgbyte.topic)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.topic/web/plugins/com.msgbyte.topic/manifest.json)
### com.msgbyte.welcome Group Welcome
Send a welcome message when joining a group
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.welcome/web/plugins/com.msgbyte.welcome)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.welcome/web/plugins/com.msgbyte.welcome/manifest.json)
### com.msgbyte.wxpusher wxpusher
Add support for wxpusher to notify user
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.wxpusher/web/plugins/com.msgbyte.wxpusher)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/server/plugins/com.msgbyte.wxpusher/web/plugins/com.msgbyte.wxpusher/manifest.json)

20
website/docs/plugin-list/theme.md Normal file
View File

@@ -0,0 +1,20 @@
---
sidebar_position: 2
title: Custom Theme (2)
---
### com.msgbyte.theme.genshin Genshin Theme
Genshin Theme
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.theme.genshin)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.theme.genshin/manifest.json)
### com.msgbyte.theme.miku Hatsune Miku Theme
Hatsune Miku theme, supports light and dark colors
- [Source Code](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.theme.miku)
- [manifest.json](https://github.com/msgbyte/tailchat/blob/master/client/web/plugins/com.msgbyte.theme.miku/manifest.json)

4
website/docs/plugins/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Develop plugins",
"position": 70
}

4
website/docs/plugins/api/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "API Interface",
"position": 99
}

249
website/docs/plugins/api/common.md Normal file
View File

@@ -0,0 +1,249 @@
---
sidebar_position: 1
title: "@capital/common"
---
## register
### regGroupPanel
Register Group Panel
```typescript
regGroupPanel({
name: `com.msgbyte.webview/grouppanel`,
label: 'web panel',
provider: PLUGIN_NAME,
extraFormMeta: [{ type: 'text', name: 'url', label: 'URL' }],
render: GroupWebPanelRender,
});
```
Parameter type: [PluginGroupPanel](#plugingrouppanel)
### regMessageInterpreter
register message interpreter
```typescript
regMessageInterpreter({
name: 'Meow language translation',
explainMessage(message: string) {
// Meow -> Human
if (!isMiao(message)) {
return null;
}
return decode(message);
},
});
```
Parameter type: [PluginMessageInterpreter](#pluginmessageinterpreter)
### regMessageRender
*Multiple registrations only take effect for the last one*
Register a message renderer, enter the message text and return the rendered content
```typescript
regMessageRender((message) => {
return <BBCode plainText={message} />;
});
```
### regChatInputAction
Register chat input box operation
```typescript
regChatInputAction({
label: 'Meow words',
onClick: (actions) => {
openModal(createElement(SendMiaoModal, { actions }));
},
});
```
Parameter Type: [ChatInputAction](#chatinputaction)
### regPluginColorScheme
Register plugin color schemes/themes
```typescript
regPluginColorScheme({
label: 'Miku onion',
name: 'light+miku',
});
```
## Utility function
### useGroupPanelParams
Get user panel related information in `hooks`
```typescript
import { useGroupPanelParams } from '@capital/common';
const { groupId, panelId } = useGroupPanelParams();
```
### openModal
open a modal
```typescript
openModal(
content: React.ReactNode,
props?: Pick<ModalProps, 'closable' | 'maskClosable'>
)
```
type:
- [ModalProps] (#modalprops)
### ModalWrapper
Modal Wrapper
```jsx
<ModalWrapper>
<div></div>
</ModalWrapper>
```
### useModalContext
Get the modal context
```typescript
const { closeModal } = useModalContext();
```
### getGlobalState
Get the global `Redux` state context
```typescript
const state = getGlobalState();
```
### getCachedUserInfo
Get user information, cached version
```typescript
const info = getCachedUserInfo(userId);
```
### getCachedConverseInfo
Get session information
```typescript
const info = getCachedConverseInfo(converseId);
```
## type
### PluginGroupPanel
```typescript
interface PluginGroupPanel {
/**
* The unique identification of the panel
* @example com.msgbyte.webview/grouppanel
*/
name: string;
/**
* panel display name
*/
label: string;
/**
* Plug-in provider, used to guide users who have not installed the plug-in to install the plug-in
*/
provider: string;
/**
* Additional form data, used when creating panels
*/
extraFormMeta: FastFormFieldMeta[];
/**
* How the panel is rendered
*/
render: React. ComponentType;
}
```
### PluginMessageInterpreter
Plugin Message Interpreter
```typescript
interface PluginMessageInterpreter {
name?: string;
explainMessage: (message: string) => React. ReactNode;
}
```
### ChatInputAction
Message input box operation object
```typescript
interface ChatInputAction {
label: string;
onClick: (actions: ChatInputActionContextProps) => void;
}
```
###GroupPanel
```typescript
interface GroupPanel {
id: string; // unique in the group
name: string;
parentId?: string;
type: GroupPanelType;
provider?: string; // panel provider
pluginPanelName?: string; // plugin panel name
meta?: Record<string, unknown>;
}
```
### ModalProps
```typescript
interface ModalProps {
visible?: boolean;
onChangeVisible?: (visible: boolean) => void;
/**
* Whether to display the close button in the upper right corner
* @default false
*/
closable?: boolean;
/**
* Whether the mask layer can be closed
*/
maskClosable?: boolean;
}
```

22
website/docs/plugins/api/component.md Normal file
View File

@@ -0,0 +1,22 @@
---
sidebar_position: 2
title: "@capital/component"
---
### Button
Components from [antd](https://ant.design/)
Component Documentation: [Button](https://ant.design/components/button-cn/)
###TextArea
Components from [antd](https://ant.design/)
Component document: [TextArea](https://ant.design/components/input-cn/#components-input-demo-textarea)
### Image
Components from [antd](https://ant.design/)
Component Documentation: [Image](https://ant.design/components/image-cn/)

9
website/docs/plugins/api/cssvar.md Normal file
View File

@@ -0,0 +1,9 @@
---
sidebar_position: 3
title: Global CSS Variables
---
- `--tc-primary-color`: primary color
- `--tc-background-image`: background image
- `--tc-content-background-image`: content page background image
- `--tc-content-background-image-opacity`: content page background image opacity, default **0.15**

19
website/docs/plugins/api/role.md Normal file
View File

@@ -0,0 +1,19 @@
---
sidebar_position: 4
title: "data-tc-role"
---
`Tailchat Role` is a way to identify the DOM through `data-*`, indicating the role of the node in `Tailchat`, developers can use this to find the DOM node corresponding to the role
Example: `[data-tc-role=navbar]`
- `navbar`: navigation bar
- `navbar-personal`: personal homepage in the navbar
- `navbar-groups`: Groups in the navbar
- `navbar-settings`: settings in the navbar
- `sidebar-personal`: sidebar in personal homepage
- `sidebar-group`: sidebar in group
- `content-personal`: the content of the personal homepage
- `content-group`: the content of the group page
- `modal`: modal box
- `modal-mask`: the mask layer of the modal box

4
website/docs/plugins/guide/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Guide",
"position": 5
}

213
website/docs/plugins/guide/create-theme.md Normal file
View File

@@ -0,0 +1,213 @@
---
sidebar_position: 2
title: Create Theme Plugin
---
It is very convenient to develop plugin in `Tailchat`. We start from developing a theme plugin
## Final Effect
![](/img/tutorial/plugin/2.png)
![](/img/tutorial/plugin/3.png)
![](/img/tutorial/plugin/4.png)
## Create Plugin
> If it is the first development, it is necessary to ensure that the plugin development environment has been initialized. [Learn more](./init-env.md)
```bash
tailchat create --template client-plugin
```
Since the theme style is a pure front-end implementation, we choose the `client-plugin` template
Complete creation via interactive command line prompts
![](/img/tutorial/plugin/5.png)
At this point the directory structure should look like this:
```
.
├── package-lock.json
├── package.json
├── node_modules
└── plugins
└── com.test.hutao
├── manifest.json
├── package.json
├── src
│   ├── index.tsx
│   └── translate.ts
├── tsconfig.json
└── types
└── tailchat.d.ts
```
At this time we can start to compile the plugin immediately
```bash
npm run plugins:all
```
The compiled product will appear in `/dist/plugins/com.test.hutao`. By modifying the configuration of the `mini-star", it can allow it to output in other directory *(this will be used in the service side development plugin)*.
## Install plugin in Tailchat
For the frontend plugin, we need to provide the product with an HTTP static service, such as in local development, we can do this:
```bash
npx http-server .
```
![](/img/tutorial/plugin/6.png)
At this time we can access the results of our compilation through the address, such as [http://127.0.0.1:8080/dist/plugins/com.test.hutao/index.js](http://127.0.0.1:8080/dist/plugins/com.test.hutao/index.js)
A manual installation plugin is provided in Tailchat. We can install the plugin by manual install.
Copy the contents of `plugins/com.test.hutao/manifest.json` in the plugin directory, paste to the manual install plugin part.
Modify the URL as the real address that can be accessed. After clicking the Submit button, the installation command is automatically executed:
![](/img/tutorial/plugin/7.png)
If the installation is prompted successfully, you can see the corresponding output when opening the console:
![](/img/tutorial/plugin/8.png)
Here is the logic generated by the default in the plugin. The prompts that the plugin after the plugin is loaded, means that our plugin has been successfully installed.
## Write style files and apply
Because we need to modify the theme style, we involve the processing of style files and static resources. Next, let's create the style of our theme first
Write in `plugins/com.test.hutao/src/theme.less`:
```less
#tailchat-app.theme-genshin-hutao {
@primary-color: #dd5545;
--tc-primary-color: @primary-color;
--tc-background-image: url(./bg.jpg);
--tc-content-background-image: url(./avatar.png);
--tc-content-background-image-opacity: 0.15;
.bg-navbar-light {
background-color: @primary-color;
.bg-gray-400 {
background-color: darken(@primary-color, 10%);
}
}
.bg-sidebar-light {
background-color: lighten(@primary-color, 20%);
}
.bg-content-light {
background-color: lighten(@primary-color, 40%);
}
&.dark {
--tc-primary-color: darken(@primary-color, 10%);
.dark\:bg-navbar-dark {
background-color: darken(@primary-color, 40%);
}
.dark\:bg-sidebar-dark {
background-color: darken(@primary-color, 20%);
}
.dark\:bg-content-dark {
background-color: @primary-color;
}
}
}
```
This style file has done three things:
- In the method of specifying the main color by the method of the `less variable`, which greatly reduces the redundant code
- In the background map of the `Tailchat` by `css variable`, mainly the background map and avatar of the login page
- Stop at the root node `#tailchat-app.theme-genshin-hutao` selector to ensure that it will not pollute the global style.
**Correspondingly, you need to put the `bg.jpg` and` avatar.png` as a static resource at the root node**
In order for `Tailchat` to know that there is such a topic, we need to register the information related to this topic into Tailchat.
```js
// plugins/com.test.hutao/src/index.tsx
import { regPluginColorScheme, sharedEvent } from '@capital/common';
regPluginColorScheme({
label: '原神-胡桃测试主题',
name: 'light+genshin-hutao',
});
sharedEvent.on('loadColorScheme', (colorSchemeName) => {
if (colorSchemeName === 'light+genshin-hutao') {
console.log('正在加载胡桃主题...');
import('./theme.less');
}
});
```
This plugin does two things:
- Call `regPluginColorScheme` to register the theme life into `Tailchat`, so that `Tailchat` will display the theme in the system settings.
- It should be noted that the `name` of the theme is composed of `<color>+<theme-name>`, the default Tailchat will provide `auto`/`light`/`dark` three color schemes, here it means to add a style override based on the bright color mode.
- Listen to the theme loading event through `sharedEvent`, if the color theme is our theme, then load the theme asynchronously (the purpose of asynchronous loading is to reduce meaningless network requests)
At this time, our compilation cannot pass, because the file of less type has not been processed yet
`mini-star` has already processed the less file by default, we only need to install the `less` package, and `mini-star` will automatically call the installed less to compile.
```bash
npm install less
```
At this time, execute `npm run plugins:all` to compile, and the final directory should be as follows:
```
.
├── dist
│   └── plugins
│   └── com.test.hutao
│   ├── index.js
│   ├── index.js.map
│   ├── theme-475203da.js
│   └── theme-475203da.js.map
├── package-lock.json
├── package.json
└── plugins
└── com.test.hutao
├── manifest.json
├── package.json
├── src
│   ├── avatar.png
│   ├── bg.jpg
│   ├── index.tsx
│   ├── theme.less
│   └── translate.ts
├── tsconfig.json
└── types
└── tailchat.d.ts
```
For ease of management, `mini-star` will directly package images in the format of `base64` into the style file when processing the static resources referenced by less. Therefore, the theme file will be very large, which is why we need to load it asynchronously on demand.
![](/img/tutorial/plugin/9.png)
Because we have installed the plugin we are developing in Tailchat before, so just refresh it directly.
Click on the theme page of system settings in the setting menu in the lower left corner, and we can see our theme. Switch to the past and immediately the interface will become the theme style we want.
![](/img/tutorial/plugin/10.png)
## Reference
The official implementation of this theme can be accessed at [https://github.com/msgbyte/tailchat/tree/master/client/web/plugins/com.msgbyte.theme.genshin](https://github.com/msgbyte/tailchat/tree/master/client/web/plugins/com.msgbyte.theme.genshin) View

54
website/docs/plugins/guide/deploy.md Normal file
View File

@@ -0,0 +1,54 @@
---
sidebar_position: 90
title: Deploy Plugin
---
:::info
The deployment strategy of the plugin will be optimized in the future. At present, tailchat is not convenient enough to customize the plugin during deployment, so it may be a little confusing. Therefore, this document only represents the status quo and will be continuously improved in the future
:::
First, let’s talk about the classification of Tailchat plugins. Tailchat plugins are divided into `pure frontend plugins`, `pure backend plugins`, `frontend plugins`
`Pure frontend plugin` is the easiest to understand, which means that the plugin only runs in the frontend code, relies on the existing context for communication, and does not need Tailchat backend support. (In particular, frontend plugins that communicate with custom backends, such as the `com.msgbyte.ai-assistant` plugin)
`Pure backend plugin is` a plugin that communicates with the Tailchat network, without a frontend interface, and calls actions of other services through rpc to achieve some purposes. For the backend plugin, it means that the plugin itself is connected to the Tailchat backend network, has the highest authority, and can access some actions whose visibility is `public` (by default, only actions at the `publish` level can be accessed externally, others level are only accessible to internal services), a frontend-free backend plugin such as `com.msgbyte.simplenotify` plugin
`Frontend plugin` means a plugin with both frontend and backend. It is the most complex but most capable plugin type. It interacts with the backend through the frontend plugin and interacts with other services through the backend plugin without modifying the core code. Can complete most of the development work under the premise of
You can check the corresponding plugin example in this document: [plugin list](/docs/plugin-list/fe)
## Deployment process
The process of deploying different plugins is different
### Pure frontend plugin
For pure frontend plugins, you can place the code in the `client/web/plugins` directory inside the project or use a separate static file service management. Make sure that the js documents of the project can be accessed normally.
If this is a plugin for personal use, you can install it through the manual installation of the plugin center, and enter the json configuration of `manifest.json`. Pay attention to ensure that the addresses in the configuration file can be accessed normally.
If you want all users to see the code, you need to add your own plugin configuration in `client/web/registry.json`.
If you want to be a built-in plugin installed by default, you need to modify the `client/web/src/plugin/builtin.ts` file to let the frontend code load the plugin at startup.
### Pure backend plugin
In order for the plugin to be loaded automatically, you can place the code in the `server/plugins` directory or deploy it independently, just make sure you can connect to the same network (share the same TRANSPORTER)
The plugin service deployed by default will uniformly load all backend plugins in this directory. Need to ensure that the name of the plugin service is `*.service.ts`/`*.service.js`
*If you only want to run in the development environment and ignore it in the production environment, please name the file `*.service.dev.ts`*
You can access the backend `/health` (such as: `http://localhost:11000/health`) route or use the `tailchat connect` tool to view the list of loaded microservices
### Frontend and backend plugins
The deployment of the frontend and backend plugins is similar to that of the backend, but the compilation command needs to be modified so that the frontend code of the frontend and backend plugins can be deployed to the `public/plugins` directory when building
The specific method is: modify `package.json`, add the name of the plugin you want to compile in the `build:server` command
> {BACKEND} in the configuration file refers to the backend address, because the backend address is not necessarily consistent with the frontend address due to the separation of the front and back ends
--------
Remember to rebuild the docker image after all operations are done

62
website/docs/plugins/guide/init-env.md Normal file
View File

@@ -0,0 +1,62 @@
---
sidebar_position: 1
title: Init Plugin Develop Env
---
Before developing a plugin, we need to create a plugin development environment. This environment can directly reuse the plugin environment of Tailchat official source code ([https://github.com/msgbyte/tailchat/tree/master/client/web/plugins](https://github.com/msgbyte/tailchat/tree/master/client/web/plugins)), It can also be an independent project
Here we mainly teach you how to create an independent plugin development environment
## frontend plugin development environment
It is very simple to create a plugin. Before that, if we did not initialize the plugin environment, we need to initialize the development environment first
Let's just find a place to build a project folder:
```bash
mkdir tailchat-plugin-test && cd tailchat-plugin-test
```
Execute in the root directory:
```bash
npm init -y
npm install mini-star
```
Create the configuration file of the `mini-star` in the root directory which named `.ministarrc.js`, the content is as follows:
```js
// .ministarrc.js
const path = require('path');
module.exports = {
externalDeps: [
'react',
'react-router',
'axios',
'styled-components',
'zustand',
'zustand/middleware/immer',
],
};
```
Write a compilation script in `package.json`
```json
{
//...
"scripts": {
// ...
"plugins:all": "ministar buildPlugin all",
"plugins:watch": "ministar watchPlugin all",
// ...
}
//...
}
```
## backend plugin development environment
TODO

51
website/docs/plugins/guide/typescript-support.md Normal file
View File

@@ -0,0 +1,51 @@
---
sidebar_position: 2
title: Typescript Support
---
In `Tailchat`, there are some utility functions or components shared from the core project, which you can import via `@capital/common` or `@capital/component`.
Of course, there are some type issues if quoted directly. Because at this time, the type system of typescript does not know what can be introduced and what types there are.
There may be two situations here:
## Develop in the Tailchat ontology project
You can import files in the same directory through the `paths` field of `tsconfig.json`, so that typescript can directly load the complete type system when parsing
for example:
```json
{
"compilerOptions": {
"baseUrl": "./src",
"esModuleInterop": true,
"jsx": "react",
"paths": {
"@capital/*": ["../../../src/plugin/*"],
}
}
}
```
## Develop in a standalone project
You can develop by getting Tailchat's pre-generated declaration files.
> Because the type needs to be manually rewritten then some types are still any. But it can guarantee that developers will not introduce functions that do not exist
If you are using the `tailchat create` command to create the project, the command line tool template has added the following commands for you
```json
"scripts": {
"sync:declaration": "tailchat declaration github"
},
```
usage
```bash
pnpm sync: declaration
```
This command will automatically pull the remote configuration file and write it into the `types/tailchat.d.ts` file in the current directory. If you manually created the project, you can add it to your `package.json` for subsequent use

20
website/docs/plugins/icon.md Normal file
View File

@@ -0,0 +1,20 @@
---
sidebar_position: 10
title: Icon
---
```ts
import { Icon } from '@capital/component';
```
The icon solution for `tailchat` comes from `iconify`
The way of use is very simple:
- Select the desired icon from the following website: [https://icon-sets.iconify.design/](https://icon-sets.iconify.design/)
- Duplicate the selected key. Pass to `Icon` component, example:
```tsx
<Icon icon="mdi:account" />
```
It is recommended to use `mdi` to unify icon visual design:
[https://icon-sets.iconify.design/mdi/](https://icon-sets.iconify.design/mdi/)

86
website/docs/plugins/start.mdx Normal file
View File

@@ -0,0 +1,86 @@
---
sidebar_position: 1
title: Start developing plugins
---
## Learn MiniStar
`MiniStar` is a complete microkernel architecture development toolchain, and the plugin architecture of `Tailchat` is developed based on `MiniStar`.
Learn more about `MiniStar`, you can check the official documentation of `MiniStar`: [https://ministar.moonrailgun.com/](https://ministar.moonrailgun.com/)
## Create a base project
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs groupId="start">
<TabItem value="cli" label="Use the cli to quick start" default>
> First, make sure you have installed `tailchat-cli`, for command line tools, please refer to: [tailchat-cli](../cli/tailchat-cli)
Move to the project directory (can be a custom project):
```bash
tailchat create
```
Choose the template according to the actual situation
![](/img/tutorial/plugin/1.png)
</TabItem>
<TabItem value="ministar" label="Use the native ministar to create a plugin project" default>
First, create a basic npm project and install `MiniStar` globally
```bash
npm install --global mini-star
```
Execute: `ministar createPlugin` in the project to create a basic plugin
Execute: `ministar buildPlugin` in the project to compile the plugin
> It is worth mentioning that although `Tailchat` does not enforce the naming convention of plugins, it is still recommended to use `anti-domain name` naming method (similar to package naming in java), and then use `/` for the components in the plugin to split
>
> such as:
>
> Plugin name: `com.msgbyte.webview`
>
> Registration content: `com.msgbyte.webview/grouppanel`
</TabItem>
</Tabs>
## Install Plugin
### Manually install plugin
Without any presets, a general method is to construct a `manifest` configuration by yourself, and then paste the configuration file into the tab of `tailchat` to provide manual installation plug-ins for installation.
The url path of the plugin can be proxied through methods such as `oss object storage service` / `static-server`
An example `manifest.json` configuration is as follows:
```json
{
"label": "Web Panel Plugin",
"name": "com.msgbyte.webview",
"url": "/plugins/com.msgbyte.webview/index.js",
"version": "0.0.0",
"author": "msgbyte",
"description": "Provides groups with the ability to create web panels",
"requireRestart": false
}
```
## other helpful resources
- Plugin architecture kernel dependency library [MiniStar](https://ministar.moonrailgun.com/)
- From the API provided by the base project: [API Documentation](./api/common)
- Export interface source code
- [@capital/common](https://github.com/msgbyte/tailchat/blob/master/client/web/src/plugin/common/index.ts)
- [@capital/component](https://github.com/msgbyte/tailchat/blob/master/client/web/src/plugin/component/index.tsx)

26
website/docs/why.md Normal file
View File

@@ -0,0 +1,26 @@
---
sidebar_position: 2
title: Why Tailchat
---
The design of `Tailchat` is to use a plug-in architecture to meet different needs of different groups of people.
## For personal
- If you want to play with friends
- Create a group
- Divide different topics through multiple channels
- Use the web panel to share favorite web pages
- If you want to gather your own fandom
- Use bots to subscribe to your own messages and forward them to the chat panel
- Let your fans gather together without creating countless qq groups/WeChat groups
- Multiple channels allow multiple topics to be generated together
- If you are very fancy about your privacy
- Self-host to keep everything under control
## For enterprise
- The panel design meets the customized design needs of enterprises
- Plug-in architecture can facilitate secondary development based on the core
- The realization of self-host can protect the value of the enterprise and make the enterprise feel at ease
- Open source code for easy review