KnoAI 技术站

主题

file-viewer 服务运维文档 ​

宿主机本地文件浏览服务 ｜ 端口 9000 ｜ 配置日期：2026-08-13

一、服务概览 ​

/home/xxx/docs/file-viewer/serve.py   # Python 文件浏览服务（venv: file-viewer/.venv）
        │  监听 0.0.0.0:9000，根目录 /home/xxx/docs/docs
        ▼
本机 http://127.0.0.1:9000/
        │  frpc host-tcp-9000（127.0.0.1:9000 → frps 19000）
        ▼
https://ai-ear.cn:9000/   # Traefik 9000 端口反代 + basic auth（401 属正常）

管理脚本：/home/xxx/docs/start-file-viewer.sh {start|stop|restart|status}（nohup 手动方式） systemd 服务：file-viewer.service（2026-08-13 起，开机自启，推荐用法）

二、开机自启配置（2026-08-13） ​

背景 ​

宿主机重启后 file-viewer 不会自动启动，导致 frpc 日志持续报错：

[host-tcp-9000] connect to local service [127.0.0.1:9000] error: connect: connection refused

配置 ​

创建 /etc/systemd/system/file-viewer.service，systemd 直接托管 Python 进程 （不再经 start-file-viewer.sh 的 nohup+PID 文件方式，systemd 自己跟踪进程）：

ini
[Unit]
Description=Docs File Viewer (serve.py :9000)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=xxx
Group=xxx
WorkingDirectory=/home/xxx/docs/file-viewer
ExecStart=/home/xxx/docs/file-viewer/.venv/bin/python serve.py /home/xxx/docs/docs --host 0.0.0.0 --port 9000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

启用：

bash
sudo systemctl daemon-reload
sudo systemctl enable --now file-viewer.service

验证结果 ​

检查结果
systemctl status file-vieweractive (running)
http://127.0.0.1:9000/200
https://ai-ear.cn:9000/（全链路）401（basic auth，未带凭据属正常）
frpc host-tcp-9000 报错消除

三、日常运维速查 ​

bash
# 状态 / 日志
systemctl status file-viewer
journalctl -u file-viewer -n 50 --no-pager

# 启停
sudo systemctl restart file-viewer
sudo systemctl stop file-viewer

# 公网访问（需 basic auth 凭据，同 /etc/nginx/.htpasswd 那套）
curl -u 用户名:xxx https://ai-ear.cn:9000/

四、注意事项 ​

  1. 不要与 start-file-viewer.sh 混用：systemd 服务和手动脚本同时用会抢 9000 端口。 日常统一用 systemctl 管理；脚本保留作应急。
  2. 该服务是 frp host-tcp-9000 代理的转发目标，服务停了公网 ai-ear.cn:9000 即 502。
  3. 根目录为 /home/xxx/docs/docs，以 xxx 用户权限运行，注意敏感文件暴露面。

关联文档：../traefik/README.md（Traefik/frp 链路与端口映射）