AAA
799d6efb4a
## Problem and outcome / 问题与结果 Browser sharing can remain connected to a local encoding transport that never becomes usable, leaving viewers without frames. This phase bounds that startup at eight seconds and restores ordinary encoding through the existing failure path. It also keeps ready App services running after a browser-open failure, preserves user presentation/playback choices, and aligns room feedback, illustrated hints, metrics and documentation. 部分环境下，本机编码连接一直无法建立会让观众收不到画面。本轮在八秒后进入现有降级流程，同时修复客户端启动移交、播放状态和前端反馈的一致性问题，并更新官网与中英文教程。 Closes #399. Related: #396. The release contains relevant startup/error-handling repairs, but the reporting machine has not been retested. Keep this issue open for a current-build result. #401 (optional Windows capture-border hiding) remains deferred. Release / 发布版本：**v1.3.1**. ## Release notes ### 中文 - 客户端记住上次确认的启动模式；启动移交保留已保存的语言、纯视觉模式和主题选择。 - 系统浏览器未能自动打开时，客户端继续运行，并在终端保留页面地址、重试入口和具体错误。 - 改善浏览器共享画面的启动兜底，避免 App 媒体因短暂信令中断被误判为失败。 - 音轨变化保持现有视频与观众的本机暂停状态；连接恢复和暂停恢复不再重复播放电视开机动画。 - 修复昵称编辑及长昵称查看，减少重复的角色提示，统一人物选择和连接状态的区别。 - 完善房间准入、密码和邀请说明；复制反馈对应当前链接及当前操作，避免迟到结果覆盖新反馈。 - 修正采集参数、统计单位与采样区间的展示，未知参数不再用配置上限代替。 - 统一提示漫画、状态图标与动效，改善选源器还焦、键盘操作、剧场布局和触控目标尺寸。 - 服务端默认支持 20 位观众，可在配置中设为 1–20 位，房主不占观众名额。 - 更新官网、教程入口和中英文说明，清理过时预览及失用代码。 兼容说明：使用旧版 App 连接更新后的站点时，站点会优先保留自己的显示偏好。如需更改语言或主题，请在进入后的页面调整。 ### English - Remember the last confirmed App launch mode and preserve saved language, visual-mode and theme choices during launch handoff. - Keep the App running if the system browser fails to open, with the page address, retry action and error details available in the terminal. - Improve the browser sharing startup fallback and avoid treating brief signaling outages as App media failures. - Keep existing video and local pause state when audio tracks change. Reconnecting and resuming no longer replay the television startup animation over the picture. - Fix nickname editing and full-name access, remove redundant role hints, and distinguish participant selection from connection state. - Clarify room access, passwords and invitations. Copy feedback now belongs to the current link and operation, so late results cannot replace newer feedback. - Correct capture details, metric units and observation intervals. Unknown capture values are no longer replaced with configured ceilings. - Align illustrated hints, status icons and motion. Improve source-picker focus, keyboard operation, theater layout and touch targets. - Default the Server to 20 viewers, configurable from 1 to 20. The host does not count toward that limit. - Update the website, guide links and bilingual instructions, and remove obsolete previews and unused code. Compatibility: when an older App connects to an updated Site, the Site keeps its saved presentation preferences. Change language or theme on the destination page when using an older launcher. ## Verification / 验证 Non-publishing [CI candidate run 34919320511](https://github.com/TNTcraftHIM/Piik/actions/runs/34919320511) passed Go core, race, Web checks, Server/container verification and all three native App package checks at source 188376e8. Subsequent commits only update deployment documentation, status and TODO; documentation/hygiene checks passed. Product inputs are unchanged. - `npm run check`: TypeScript, 64 test files / 854 tests, and the Web production build passed. - `npm run check:client-core`: final Go source passed tests, formatting, vet and core target builds. Windows capture compilation and geometry checks passed earlier in this phase; later edits did not change native capture. - Website build, documentation checks, repository hygiene and diff checks passed. Existing documentation-size and bundle-size warnings remain. - Actual browser flows covered sharing, source changes, pause/resume, late audio, brief signaling loss, invitation/copy feedback, entry preferences, source-picker focus, and narrow layouts. - A local three-viewer P2P relay check covered quality-report expiry, recovery and cleanup without interrupting video. A controlled browser-helper failure returning `0xc0000005` left the real App launcher and Local service available. - Homepage checks covered Chinese/English, light/dark preferences and inline-film open/close after removing the separate-page entry. Limits: no new reporter-machine confirmation for #396 or the Windows URL-handler crash; physical Safari/mobile, macOS/Linux capture and wider public-network/endurance coverage remain deferred. Formal release artifacts will be built from the approved squash-merge revision. Hero-loop controls and video-adjacent tooltip placement remain open design items in TODO. ## Impact / 影响 Compatible patch; signaling, Native control and capture contracts are unchanged. Older App launch handoff keeps the updated Site's saved presentation preferences. The Server's default viewer limit is corrected to 20; an explicit 1–20 configuration remains valid. Service updates retain persisted room authority but restart active media sessions. Deploy the verified immutable Server artifact through the existing bounded health/recovery process. Public Demo remains open and P2P-only; deployment does not enable SFU or change infrastructure/configuration.
106 lines
5.5 KiB
Markdown
106 lines
5.5 KiB
Markdown
# Service Management
|
|
|
|
English · [简体中文](./service-management.zh-CN.md) · [Documentation](../README.md)
|
|
|
|
For first installation, use the [short self-hosting guide](./self-hosting.md).
|
|
This reference covers a persistent Linux service and container maintenance.
|
|
|
|
## systemd
|
|
|
|
The [service template](../../deploy/systemd/piik.service.example) runs as the
|
|
`piik` user, reads `/etc/piik/piik.env`, and starts
|
|
`/opt/piik/current/piik-server`. Create the service account and place the extracted
|
|
release at that path, or point `current` at its release directory. Copy your
|
|
configuration to `/etc/piik/piik.env` and set
|
|
`ROOM_DATABASE_PATH=/var/lib/piik/rooms.sqlite`; the unit creates this state directory.
|
|
Keep the environment file readable only by its operator.
|
|
|
|
Install the template as `/etc/systemd/system/piik.service`, then run:
|
|
|
|
```sh
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now piik
|
|
sudo systemctl status piik
|
|
```
|
|
|
|
Keep HTTP bound to loopback when the HTTPS proxy runs on the same host.
|
|
STUN and optional SFU use their own public UDP listeners. An existing nginx
|
|
installation can use the [proxy example](../../deploy/nginx/piik.conf.example)
|
|
after adapting the domain and certificate paths.
|
|
|
|
## Container
|
|
|
|
Use the [Docker Compose setup](./self-hosting.md#docker-compose) for installation.
|
|
The image is `ghcr.io/tntcrafthim/piik`, with `latest` and matching product version
|
|
tags (`vMAJOR.MINOR.PATCH`). It supports **linux/amd64**. Set `PIIK_IMAGE` in `.env`
|
|
to pin a version or image digest. Updates are explicit; pulling an image does not
|
|
replace a running container.
|
|
|
|
The [runtime Dockerfile](../../deploy/container/Dockerfile) wraps the verified
|
|
Server archive, including its Web UI, license notices and `REVISION`.
|
|
Its pinned [Distroless non-root base](https://github.com/GoogleContainerTools/distroless)
|
|
includes CA certificates and has no shell or package manager. The
|
|
[release workflow](../reference/versioning.md#container-distribution) owns
|
|
building, checking and publishing the image.
|
|
|
|
Use the existing [production configuration](../reference/configuration.md).
|
|
Keep `LISTEN_HOST=0.0.0.0` inside the container and retain the host's existing
|
|
HTTPS/WebSocket proxy. With Docker port mapping, set `SFU_PUBLIC_IP` to the
|
|
reachable server IPv4 address when SFU is enabled; container-private candidates
|
|
are not Internet-reachable. Advertised STUN names must resolve to the server's
|
|
public address, and UDP must reach the container directly.
|
|
|
|
The [Compose file](../../deploy/container/compose.yaml) keeps HTTP on host
|
|
loopback, publishes the standard UDP ports and enables automatic restart.
|
|
Publishing a port does not enable its service; `.env` controls optional listeners.
|
|
Edit both the application setting and port mapping if changing a listener port.
|
|
Run a host proxy, or adapt the proxy's container networking deliberately: its
|
|
own `127.0.0.1` does not reach Piik in another container.
|
|
|
|
The image's `/home/nonroot` is owned by UID/GID `65532:65532` with mode `0700`.
|
|
A new named volume inherits that directory; an existing volume or bind mount
|
|
must already be writable by that identity. Keep this volume when replacing the
|
|
container. Set `ROOM_DATABASE_PATH=:memory:` for memory-only room authority. Diagnostics
|
|
remain opt-in and use `/home/nonroot/logs`; [export and retention](../reference/configuration.md#diagnostics)
|
|
remain the operator's responsibility. Do not mount application files writable.
|
|
With diagnostics enabled, `docker compose kill --signal=SIGUSR1 piik` requests a local
|
|
export without stopping the container; the ZIP remains in the mounted log directory.
|
|
|
|
Check `/healthz` from the host and public proxy, then verify configured STUN/SFU
|
|
UDP and room/media behavior using [operational verification](#operational-verification).
|
|
There is no shell-based healthcheck in the image. Retain the previous image,
|
|
environment and volume backup before replacement. From the deployment directory:
|
|
|
|
```sh
|
|
docker compose pull
|
|
docker compose stop
|
|
docker compose cp piik:/home/nonroot ./piik-data-backup
|
|
docker compose up -d
|
|
docker compose logs --tail=50 piik
|
|
```
|
|
|
|
Use a new backup directory each time. Stop Piik before copying SQLite so its
|
|
database and journal are consistent. Preserve `.env` separately and protect both
|
|
backups as room credentials. Keep the same Compose project/directory so the named
|
|
volume is reused; `docker compose down --volumes` deletes that data. To roll back,
|
|
restore the previous image setting and compatible configuration, then recreate
|
|
the service. Read release notes before crossing a storage-format boundary.
|
|
The bare-metal `release-app.sh` wrapper does not manage containers.
|
|
|
|
## Operational Verification
|
|
|
|
- `/healthz` returns `{"status":"ok"}` locally and through the public origin.
|
|
- Piik and the HTTPS proxy are active with expected restart counts and bounded
|
|
logs/resources; Piik owns the configured STUN/SFU UDP listeners.
|
|
- The official Trickle ICE sample obtains an ordinary UDP `srflx` candidate from
|
|
the configured STUN service and no relay candidate.
|
|
- A direct room presents media on two networks when Peer ICE succeeds.
|
|
- When SFU is enabled, a constrained route creates one managed Host publication
|
|
and only admitted subscriptions over embedded SFU UDP; Peer descendants remain ordinary P2P.
|
|
- Blocking all UDP reaches a clear bounded failure.
|
|
- Restarting Piik in stable mode retains room authority while Browser
|
|
sessions and media reconnect from fresh process state.
|
|
|
|
Representative network, mobile, audio, 20-Viewer, and long-running evidence is
|
|
tracked in [verification status](../verification-status.md), not in this runbook.
|