Skip to content

Commit be4549f

Browse files
dnomd343dnomd343
committed
docs: add simplified Chinese README
1 parent 336c3e4 commit be4549f

File tree

2 files changed

+251
-0
lines changed

2 files changed

+251
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
## Quick Start
22

3+
[简体中文](./README_zh-CN.md)
4+
35
Using one command to start the Syncplay service. Yes, it's very simple.
46

57
```bash

‎README_zh-CN.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
## 快速开始
2+
3+
使用一句命令开启 Syncplay 服务，是的，就这么简单。
4+
5+
```bash
6+
> docker run --rm --net=host dnomd343/syncplay
7+
Welcome to Syncplay server, ver. 1.7.0
8+
```
9+
10+
> 按下 `Ctrl+C` 将退出服务
11+
12+
如果没有意外，您可以在客户端填入服务器 IP 或域名进行验证，默认端口是 `tcp/8999`。若无法连上，请检查您的防火墙设置。
13+
14+
为了更好地运行服务，我们应当使用以下命令让 Syncplay 在后台运行，并保持启动。
15+
16+
```bash
17+
docker run -d --net=host --restart=always --name=syncplay dnomd343/syncplay
18+
```
19+
20+
> 您可以使用 `docker ps -a` 看到正在运行的服务，还可以使用 `docker rm -f syncplay` 停止服务。
21+
22+
您可以加入更多的参数来实现定制化，例如我们让服务器连接时需要输入密码、禁止聊天、并在进入房间后显示一句欢迎语，使用以下命令。
23+
24+
> 注意在按下回车前，您必须执行 `docker rm -f syncplay` 移除掉原有的服务，否则它们会发生冲突。
25+
26+
```bash
27+
docker run -d --net=host \
28+
--restart=always --name=syncplay \
29+
dnomd343/syncplay --disable-chat \
30+
--password=PASSWD --motd='HELLO WORLD'
31+
```
32+
33+
服务器在必要的时候会被重启，也可能是 Docker 服务或 Syncplay 需要更新，无论是不是预期中的，这个时候将 Syncplay 持久化是很有必要的，这意味着房间数据将会被保存到磁盘上。您需要选择一个工作目录来保存他们，例如 `/etc/syncplay/`，执行以下命令，数据会被保存到 `rooms.db` 文件中。
34+
35+
```bash
36+
docker run -d --net=host \
37+
--restart=always --name=syncplay \
38+
--volume /etc/syncplay/:/data/ \
39+
dnomd343/syncplay --persistent
40+
```
41+
42+
这个目录还有更多的用途，例如添加 `--enable-stats` 选项将开启统计功能，数据将被保存到目录下 `stats.db` 这个文件中。您还可以在目录下创建 `config.yml` 文件，将配置参数写在里面，Syncplay 启动时将会自动读取，避免在命令行中键入大量参数。
43+
44+
```yaml
45+
# /etc/syncplay/config.yml
46+
password: 'My Password'
47+
persistent: true
48+
enable-stats: true
49+
disable-chat: false
50+
motd: |
51+
Hello, here is a syncplay server.
52+
More information...
53+
```
54+
55+
在实际部署时，开启 TLS 总会是一个好主意（当然它不是必要的，这一步可以跳过），幸运的是，Syncplay 可以很简单地做到这一点。在开始前，您需要准备一个域名，并把它的 DNS 解析到当前服务器上，同时，我们必须拥有它的证书文件。
56+
57+
证书的申请可以通过 [`acme.sh`](https://acme.sh/) 、[`certbot`](https://certbot.eff.org/) 或者其他合理的方式进行。总之，您最终会得到一把私钥和一张证书，Syncplay 需要您提供以下三个文件。
58+
59+
+ `cert.pem` ：CA 机构签发的证书
60+
+ `chain.pem` ：CA 机构的证书链
61+
+ `privkey.pem` ：证书的私钥文件
62+
63+
例如在 `acme.sh` 中，可以这样子执行命令，将 `343.re` 这个域名的证书配置保存到 `/etc/ssl/certs/343.re/` 目录下。
64+
65+
```bash
66+
acme.sh --install-cert -d 343.re \
67+
--cert-file /etc/ssl/certs/343.re/cert.pem \
68+
--ca-file /etc/ssl/certs/343.re/chain.pem \
69+
--key-file /etc/ssl/certs/343.re/privkey.pem
70+
```
71+
72+
现在我们已经准备好了，只需要执行下面的命令，一个更安全更隐私的 Syncplay 服务将会启动。
73+
74+
```bash
75+
docker run -d --net=host \
76+
--restart=always --name=syncplay \
77+
--volume /etc/syncplay/:/data/ \
78+
--volume /etc/ssl/certs/343.re/:/certs/ \
79+
dnomd343/syncplay --persistent --enable-tls
80+
```
81+
82+
> 注意客户端的服务器地址必须与证书匹配，否则连接将会失败。
83+
84+
需要说明的是，与有些服务不同，Syncplay 在证书发生更新时不需要手动重启，它会自动检测证书的变化，并使用最新的版本。此外，Syncplay 服务端的 TLS 是自适应的，这意味着，即使是不支持 TLS 的旧版本客户端，它们仍然可以正常通讯，但是注意此时安全加密将不再生效。
85+
86+
## 命令行参数
87+
88+
您可以通过指定以下命令行参数来定制 Syncplay 服务器。
89+
90+
> 以下参数是针对 docker 调整过的，与[官方文档](https://man.archlinux.org/man/extra/syncplay/syncplay-server.1)不完全相同，使用时请以此为准。
91+
92+
+ `--port [PORT]` ：Syncplay 服务器监听端口, 默认为 `8999`
93+
94+
+ `--password [PASSWD]` ：用户登录服务器的密码，默认不启用
95+
96+
+ `--motd [MESSAGE]` ：用户进入房间的欢迎内容，默认不启用
97+
98+
+ `--salt [SALT]` ：密码加盐，指定随机字符串，用于抵抗哈希攻击（例如彩虹表），默认为空字符串
99+
100+
+ `--random-salt` ：使用随机生成的盐，仅当 `--salt` 未指定时生效，默认不启用
101+
102+
+ `--isolate-rooms` ：开启独立房间，用户将看不到其他房间的用户信息，默认不启用
103+
104+
+ `--disable-chat` ：禁止聊天功能，默认不启用
105+
106+
+ `--disable-ready` ：禁止就绪指示器功能，默认不启用
107+
108+
+ `--enable-stats` ：开启服务器统计功能，数据将被保存到 `stats.db` 文件中，默认不启用
109+
110+
+ `--enable-tls` ：开启 TLS 支持, 证书文件需要挂载到 `/certs/` 目录下，包括 `cert.pem` 、`chain.pem` 、`privkey.pem` 三个文件，默认不启用
111+
112+
+ `--persistent` ：开启房间数据持久化，信息将被保存到 `rooms.db` 文件中，仅当 `--isolate-rooms` 未指定时有效，默认不启用
113+
114+
+ `--max-username [N]` ：用户名最大长度，默认为 `150`
115+
116+
+ `--max-chat-message [N]` ：聊天消息最大长度，默认为 `150`
117+
118+
+ `--permanent-rooms [ROOM ...]` ：即使播放列表为空时仍会列出的房间，仅当 `--persistent` 指定时有效，默认为空
119+
120+
您也可以使用以下命令输出帮助信息。
121+
122+
```bash
123+
> docker run --rm syncplay --help
124+
usage: syncplay [-h] [-p PORT] [--password PASSWORD] [--motd MOTD]
125+
[--salt SALT] [--random-salt] [--isolate-rooms]
126+
[--disable-chat] [--disable-ready] [--enable-stats]
127+
[--enable-tls] [--persistent] [--max-username MAX_USERNAME]
128+
[--max-chat-message MAX_CHAT_MESSAGE]
129+
[--permanent-rooms [PERMANENT_ROOMS ...]]
130+
131+
Syncplay Docker Bootstrap
132+
133+
optional arguments:
134+
-h, --help show this help message and exit
135+
-p PORT, --port PORT listen port of syncplay server
136+
--password PASSWORD authentication of syncplay server
137+
--motd MOTD welcome text after the user enters the room
138+
--salt SALT string used to secure passwords
139+
--random-salt use a randomly generated salt value
140+
--isolate-rooms room isolation enabled
141+
--disable-chat disables the chat feature
142+
--disable-ready disables the readiness indicator feature
143+
--enable-stats enable syncplay server statistics
144+
--enable-tls enable tls support of syncplay server
145+
--persistent enables room persistence
146+
--max-username MAX_USERNAME
147+
maximum length of usernames
148+
--max-chat-message MAX_CHAT_MESSAGE
149+
maximum length of chat messages
150+
--permanent-rooms [PERMANENT_ROOMS ...]
151+
permanent rooms of syncplay server
152+
```
153+
154+
## 配置文件
155+
156+
如果您配置了较多的选项，每次启动时输入大量命令行参数会是相当麻烦且易出错的事情，这个时候可以将它们写到配置文件中。在工作目录中创建 `config.yml` 文件，它使用 YAML 格式，支持命令行中的所有参数，Syncplay 在启动时会自动读取并加载，但需要注意的是，如果命令行指定了同样的参数，将会覆盖配置文件的选项。
157+
158+
```yaml
159+
port: 7999
160+
salt: 'SALT'
161+
random-salt: true
162+
password: 'My Password'
163+
persistent: true
164+
enable-tls: true
165+
enable-stats: true
166+
isolate-rooms: true
167+
disable-chat: true
168+
disable-ready: true
169+
max-username: 256
170+
max-chat-message: 2048
171+
permanent-rooms:
172+
- ROOM_1
173+
- ROOM_2
174+
- ROOM_3
175+
motd: |
176+
Hello, here is a syncplay server.
177+
More information...
178+
```
179+
180+
## Docker Compose
181+
182+
使用 `docker-compose` 来部署 Syncplay 是一种更优雅的方式，你需要创建一个 `docker-compose.yml` 配置文件，写入以下的示例。
183+
184+
```yaml
185+
# /etc/syncplay/docker-compose.yml
186+
version: '3'
187+
services:
188+
syncplay:
189+
container_name: syncplay
190+
image: dnomd343/syncplay
191+
network_mode: host
192+
restart: always
193+
volumes:
194+
- ./:/data/
195+
```
196+
197+
我们将这个文件保存在 `/etc/syncplay/` 目录下，由于使用了相对路径，因此它也同样处于工作目录中，在该目录下执行命令启动 Syncplay 服务。
198+
199+
```bash
200+
> docker-compose up
201+
Recreating syncplay ... done
202+
Attaching to syncplay
203+
syncplay | Welcome to Syncplay server, ver. 1.7.0
204+
```
205+
206+
> 添加 `-d` 选项可以让服务在后台运行。
207+
208+
类似的，您可以映射证书目录来开启 TLS 功能，以及编辑 `config.yml` 文件来配置更多选项。
209+
210+
## 错误排查
211+
212+
如果您遇到了任何错误，请先使用 `docker logs syncplay` 命令打印进程输出内容，它可能包含有用的错误信息，您还可以通过指定环境变量 `DEBUG=ON` 来输出更详细的日志。
213+
214+
```bash
215+
> docker run --rm --env DEBUG=ON dnomd343/syncplay
216+
Command line arguments -> Namespace(port=None, password=None, motd=None, salt=None, random_salt=False, isolate_rooms=False, disable_chat=False, disable_ready=False, enable_stats=False, enable_tls=False, persistent=False, max_username=None, max_chat_message=None, permanent_rooms=None)
217+
Parsed arguments -> {}
218+
Syncplay startup arguments -> ['--port', '8999', '--salt', '']
219+
Welcome to Syncplay server, ver. 1.7.0
220+
```
221+
222+
## 容器构建
223+
224+
您可以直接从源码中构架出镜像，使用以下命令。
225+
226+
```bash
227+
docker build -t syncplay https://github.com/dnomd343/syncplay-docker.git
228+
```
229+
230+
您也可以更改源代码来实现自己的定制。
231+
232+
```bash
233+
> git clone https://github.com/dnomd343/syncplay-docker.git
234+
> cd syncplay-docker/
235+
# some edit...
236+
> docker build -t syncplay .
237+
```
238+
239+
如果您需要多种架构的镜像，请使用 `buildx` 命令构建。
240+
241+
```bash
242+
docker buildx build -t dnomd343/syncplay \
243+
--platform=linux/amd64,linux/386,linux/arm64,linux/arm/v7 \
244+
https://github.com/dnomd343/syncplay-docker.git --push
245+
```
246+
247+
## 许可证
248+
249+
MIT ©2022 [@dnomd343](https://github.com/dnomd343)

0 commit comments

Comments
 (0)