手把手教你启动Fun-ASR，localhost访问不求人

手把手教你启动Fun-ASR，localhost访问不求人

你是不是也经历过这样的场景：下载完 Fun-ASR 镜像，解压、配置、折腾半天，终端里跑出一串日志，却始终打不开http://localhost:7860？浏览器显示“拒绝连接”，或者页面空白、按钮无响应？别急——这不是模型的问题，也不是你的电脑不行，而是启动流程中漏掉了几个关键动作。

Fun-ASR 是钉钉与通义实验室联合推出的轻量级语音识别系统，由开发者“科哥”完成镜像封装，开箱即用。它不像传统 ASR 那样需要手动装依赖、配环境、写服务脚本；但正因高度集成，它的启动逻辑反而更“讲究”：路径对不对、权限够不够、端口占没占、GPU 能不能用……任何一个环节卡住，都会让你在 localhost 前止步。

本文不讲模型原理，不堆参数配置，只做一件事：带你从零开始，5 分钟内真正跑通 Fun-ASR WebUI，让浏览器稳稳打开那个熟悉的界面，上传音频、点击识别、看到文字一行行跳出来。全程基于真实部署经验，避开所有新手高频踩坑点，连 bash 报错提示都给你标清楚了怎么读。

1. 启动前必查的三件事

在敲下第一行命令前，请花 60 秒确认这三项。90% 的“打不开 localhost”问题，都出在这里。

1.1 检查镜像是否完整解压

Fun-ASR 镜像通常以.tar或.zip形式提供。解压后，目录结构必须包含以下核心文件（缺一不可）：

funasr-webui/ ├── start_app.sh ← 启动脚本（必须可执行） ├── app.py ← 主程序入口 ├── webui/ ← 前端资源目录 │ └── data/history.db ← 历史数据库（首次运行会自动生成） ├── models/ ← 模型存放目录（若为空，首次启动会自动下载） └── requirements.txt

常见错误：

• 解压时用了“仅解压顶层目录”，导致start_app.sh跑在错误路径下；
• 用 Windows 解压工具解压 Linux 镜像，丢失了start_app.sh的可执行权限（chmod +x缺失）。

验证方法：
进入解压后的根目录，运行：

ls -l start_app.sh

正确输出应包含x（如-rwxr-xr-x）。若没有，立即修复：

chmod +x start_app.sh

1.2 确认 Python 与依赖已就绪

Fun-ASR WebUI 基于 Python 3.9+ 和 Gradio/FastAPI 构建。无需全局安装，但需确保基础环境可用。

快速验证：

python3 --version # 应输出 Python 3.9.x 或更高版本 which pip3 # 确保 pip3 可用

若提示command not found，请先安装 Python 3.9+（Ubuntu/Debian 推荐apt install python3.9 python3.9-venv；CentOS 用dnf install python39）。

注意：不要用python（Python 2）或pip（可能指向旧版），务必统一使用python3和pip3。

1.3 检查 7860 端口是否被占用

Fun-ASR 默认监听localhost:7860。如果该端口已被其他程序（如另一个 Gradio 应用、Jupyter Lab、甚至某个残留进程）占用，start_app.sh会静默失败或报错。

检查命令（Linux/macOS）：

lsof -i :7860 # 或 netstat -tuln | grep :7860

若返回结果非空，说明端口被占。可选择：

• 杀掉占用进程（kill -9 <PID>）；
• 或修改启动端口（见后文“进阶技巧”）。

2. 一行命令启动，但得知道它在做什么

官方文档只写了bash start_app.sh，但这一行背后有三层动作。理解它，才能快速定位问题。

2.1 启动脚本实际执行流程

start_app.sh并非简单运行python3 app.py，它做了三件关键事：

1. 自动创建虚拟环境（venv）
   若当前目录下无venv/文件夹，脚本会执行：

   python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

   这意味着：首次运行会联网安装依赖（约 2–5 分钟），需保持网络畅通。

2. 智能检测计算设备
   脚本会尝试调用nvidia-smi（NVIDIA GPU）或system_profiler（Mac M 系列），自动判断是否启用 CUDA/MPS。若检测失败，默认回退至 CPU 模式——速度慢但能跑通。

3. 带参数启动 FastAPI 服务
   最终执行类似：

   python3 app.py --host 0.0.0.0 --port 7860 --device cuda

   其中--host 0.0.0.0是关键：它允许本地和局域网访问；而localhost仅限本机，所以必须用此参数。

因此，正确启动姿势是：

cd /path/to/funasr-webui bash start_app.sh

2.2 启动过程中的关键日志信号

启动时，终端会滚动输出日志。请重点关注以下三类信息：

特别提醒：若日志卡在Loading model...超过 3 分钟，大概率是模型未预下载，且网络不佳导致超时。此时请参考后文“离线部署方案”。

3. 浏览器打不开？分四步精准排查

即使start_app.sh显示“Running on local URL”，浏览器仍可能打不开。按顺序检查：

3.1 第一步：确认服务真正在运行

不要只信终端最后一行。新开一个终端，执行：

ps aux | grep "app.py\|gradio"

若看到类似python3 app.py --host 0.0.0.0 --port 7860的进程，说明服务活着；若无，则脚本已异常退出。

快速重启法：

# 杀掉所有相关进程 pkill -f "app.py" pkill -f "gradio" # 重新启动 bash start_app.sh

3.2 第二步：用 curl 直接测试接口

绕过浏览器，用命令行验证服务是否响应：

curl -I http://localhost:7860

正常返回应为：

HTTP/1.1 200 OK ...

若返回curl: (7) Failed to connect，说明服务未监听或端口错误。

进阶测试（检查 WebUI 根路径）：

curl http://localhost:7860 | head -20

应看到 HTML 片段，如<title>Fun-ASR WebUI</title>—— 这证明前端资源已正确加载。

3.3 第三步：检查浏览器访问方式

• 正确：http://localhost:7860或http://127.0.0.1:7860
• ❌ 错误：https://localhost:7860（Fun-ASR 不启用 HTTPS）、http://localhost（缺端口）、http://funasr-webui.local（未配 DNS）

Chrome/Firefox 安全策略提示：若页面空白且控制台报Mixed Content错误，说明某处资源被强制 HTTPS 加载。此时请清空浏览器缓存（Ctrl+Shift+R 强制刷新），或换用 Edge 浏览器。

3.4 第四步：防火墙与 SELinux（Linux 专属）

Ubuntu/CentOS 默认防火墙可能拦截 7860 端口。

临时放行（测试用）：

# Ubuntu (UFW) sudo ufw allow 7860 # CentOS (firewalld) sudo firewall-cmd --add-port=7860/tcp --permanent sudo firewall-cmd --reload

关闭 SELinux（仅开发环境）：

sudo setenforce 0 # 永久关闭：编辑 /etc/selinux/config，设 SELINUX=disabled

4. 四大高频问题实战解决

根据上百次部署反馈，整理最常遇到的四个“卡点”，附带一键修复命令。

4.1 问题：启动后页面加载缓慢，按钮点击无反应

原因：Gradio 前端资源（JS/CSS）首次加载需从 HuggingFace CDN 下载，国内直连极慢，导致界面卡在“Loading…”。

解决方案：启用国内静态资源代理
编辑app.py，在import gradio as gr后添加：

import os os.environ["GRADIO_STATIC_ROOT"] = "https://hf-mirror.com/gradio-static"

然后重启服务。Gradio 将从国内镜像加载前端资源，加载时间从数分钟降至 2 秒内。

4.2 问题：上传音频后提示“Error: No audio file provided”

原因：WebUI 使用gr.File组件，但某些浏览器（尤其 Safari）对文件拖拽支持不完善；或上传文件过大触发 Gradio 默认限制（100MB）。

双保险修复：

1. 改用 Chrome/Edge 浏览器（官方推荐）；
2. 增大上传限制：在app.py中找到gr.Interface(...)初始化处，添加参数：

   examples=[], allow_flagging="never", max_file_size="500MB" # 改为 500MB

4.3 问题：实时流式识别点击麦克风无反应，或识别结果为空

原因：浏览器未获麦克风权限，或 Fun-ASR 的 VAD 模块未正确初始化。

三步修复：

1. 地址栏点击锁形图标 → “网站设置” → “麦克风” → 设为“允许”；
2. 刷新页面后，首次点击麦克风图标时，浏览器会弹出授权框，务必点“允许”；
3. 若仍无效，在 WebUI 的“系统设置”中，将“计算设备”手动切换为CPU（VAD 在 CPU 模式下更稳定）。

4.4 问题：批量处理中途崩溃，历史记录消失

原因：SQLite 数据库history.db被多进程同时写入，导致文件锁冲突（尤其在 macOS 上高发）。

根治方案：强制单线程写入
编辑webui/utils/history_manager.py（若存在），或在app.py中找到数据库操作部分，确保所有写操作加锁：

import threading db_lock = threading.Lock() def save_record(record): with db_lock: # 原始写入代码 conn.execute("INSERT INTO history ...") conn.commit()

重启后，批量处理将稳定运行。

5. 进阶技巧：让 Fun-ASR 更好用、更省心

启动只是第一步。这些技巧能帮你把 Fun-ASR 从“能用”变成“好用”。

5.1 自定义启动端口与绑定地址

不想用 7860？或想让同事通过局域网访问？修改start_app.sh中的启动命令：

# 原始 python3 app.py --host 0.0.0.0 --port 7860 # 改为（例如用 8080 端口，仅限本机） python3 app.py --host 127.0.0.1 --port 8080 # 或（局域网可访问，假设本机 IP 是 192.168.1.100） python3 app.py --host 0.0.0.0 --port 7860

注意：--host 0.0.0.0允许外部访问，生产环境务必配合 Nginx 反向代理 + Basic Auth。

5.2 离线部署：彻底告别网络依赖

若服务器无外网，或需在内网长期运行，可提前准备：

1. 预下载模型（在有网机器上）：

   export HF_ENDPOINT=https://hf-mirror.com huggingface-cli download funasr/funasr-nano-2512 --local-dir ./models/funasr-nano-2512

2. 打包整个目录（含models/、venv/、webui/）；
3. 在目标机器解压后，注释掉start_app.sh中的pip install行，直接运行python3 app.py。

5.3 日志与性能监控

默认日志不保存。添加日志记录，便于排障：

# 修改 start_app.sh，末尾改为： nohup python3 app.py --host 0.0.0.0 --port 7860 > logs/app.log 2>&1 & echo $! > logs/pid.txt

之后可通过tail -f logs/app.log实时追踪。

5.4 开机自启（Linux systemd）

让 Fun-ASR 成为系统服务，断电重启后自动拉起：

sudo tee /etc/systemd/system/funasr.service << 'EOF' [Unit] Description=FunASR WebUI After=network.target [Service] Type=simple User=$USER WorkingDirectory=/path/to/funasr-webui ExecStart=/bin/bash -c 'cd /path/to/funasr-webui && source venv/bin/activate && python3 app.py --host 0.0.0.0 --port 7860' Restart=always RestartSec=10 [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable funasr sudo systemctl start funasr

6. 总结：你已经掌握了本地语音识别的主动权

回顾一下，我们完成了什么：

• 一次启动就成功：绕过权限、端口、依赖三大陷阱，让localhost:7860稳稳亮起；
• 四类顽疾全解决：页面加载慢、上传失败、麦克风失灵、批量崩溃，都有对应的一键修复；
• 进阶能力已解锁：自定义端口、离线部署、日志监控、开机自启，让 Fun-ASR 真正融入你的工作流。

Fun-ASR 的价值，从来不在模型多大、参数多深，而在于它把语音识别这件事，压缩成一个可执行的文件、一个浏览器标签页、一次点击就能出结果的确定性体验。当你第一次把会议录音拖进界面，30 秒后看到逐字稿整齐排列，那种“技术终于听懂人话”的踏实感，就是所有调试的意义所在。

现在，关掉这篇教程，打开你的终端，输入那行最朴素的命令：

bash start_app.sh

然后，静静等待那一行Running on local URL: http://localhost:7860出现——它不是终点，而是你掌控语音能力的起点。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。