Gitea Wiki 完整指南如何给项目文档加上历史、权限和回滚【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea项目文档散落在群聊、网盘和个人博客里版本对不上代码出问题还查不到是谁改的。Gitea Wiki 把每个页面存成独立 Git 仓库里的 Markdown 文件编辑历史、回滚、权限控制开箱即用。这篇指南带你从零启用 Wiki再逐步调好进阶功能。它到底解决了什么问题文档和代码版本对不上Wiki 的每次保存本身就是一次 Git 提交谁在什么时候改了什么历史记录里都能查到文档和代码天然对齐在同一个版本基线上。共享文档谁都能改Wiki 直接复用仓库的权限体系只读成员只能看、有写权限的成员才能编辑不需要再搭一套文档系统。改动没有版本可退每次保存生成一个提交任意两个版本可以对比差异写错了也能把旧内容找回来。原理一分钟看懂每个代码仓库对应一个隐藏的仓库名.wiki仓库。Wiki 在保存第一个页面前并不存在系统会自动创建入口在源码services/wiki/wiki.go的InitWiki函数。一个页面就是一个.md文件。新建、编辑、删除全部转成提交操作提交说明就是你保存时填写的那句话。页面名会被自动转成文件名逻辑在services/wiki/wiki_path.go空格变连字符特殊字符做 URL 编码_edit、_new、_pages、raw四个保留名不能用作页面名。渲染复用 Gitea 的 Markdown 引擎代码高亮、表格、链接等能力和代码页面完全一致。快速上手3 步完成第一个页面启用功能进入仓库「设置 → 功能」勾选 Wiki 并保存。没勾选时界面不会出现 Wiki 标签。创建第一个页面点「Wiki」标签选「新建页面」命名为Home写一段项目简介保存。此时系统自动建好 Wiki 仓库。验证历史生效对这个页面点「编辑」把标题改成「项目简介」保存再点页面里的「历史」能看到两条提交记录还可以对比差异。 从第 1 步到第 3 步全程不需要动服务器配置两三分钟就能走完。进阶玩法对比并找回任意历史版本打开页面的「历史」可以看到全部提交列表。点任意一条能查看当时的内容选中两条还能看差异。如果某次改动是失误把旧版本内容复制到当前页面覆盖保存即可——对文档系统来说这就是撤销功能。把 Wiki 当成普通 Git 仓库批量导入Wiki 仓库支持像普通仓库一样 clone、改文件、推送地址形如owner/repo.wiki。迁移已有文档时把 Markdown 文件拷进仓库后提交推送网页端立即可见cp -r ./docs/* gitea.wiki/ git add . git commit -m Import existing docs git push注意文件扩展名必须是.md非.md文件不会作为页面展示。给 Wiki 提交签名app.ini的[signature]段有一个专门的WIKI项控制 Wiki 提交何时签名。设为pubkey, twofa后只有配置了公钥且经过两步验证登录的用户其提交才会被签名文档改动是否出自真人就可在历史中审计。配置、性能与安全配置项所在段一句话说明WIKI[signature]Wiki 提交何时签名可选never/pubkey/twofa/alwaysRENDER_OPTIONS_WIKI[markup]设为short-issue-pattern后文档里的#123会渲染成可点击的 issue 链接CUSTOM_URL_SCHEMES[markup]限制文档里允许的链接协议留空表示全部允许Wiki 默认分支仓库设置页面默认从该分支读取支持改成与主仓库不同的分支名性能方面Wiki 没有独立缓存层每次打开页面都是直接读 Git 仓库。单页通常很小几乎不会成为瓶颈如果页面数达到数千建议把大知识库拆成多个仓库而不是堆在一个 Wiki 里。安全方面仓库被归档后 Wiki 同步只读任何人包括管理员都无法再编辑适合冻结已结项项目的文档。常见坑排查1. 新建页面提示“已存在”现象明明没重名创建时却报页面已存在。 排查系统按转换后的文件名找文件A B空格和A-B连字符会指向同一个文件。 解决换个名字确实想用连字符时直接在页面名输入框里输入连字符系统会自动保留它。2. Wiki 标签页打不开或提示无权限现象点 Wiki 标签返回 404 或权限不足。 排查先确认「设置 → 功能」里勾了 Wiki再看账号对仓库是否至少有读权限。 解决启用功能并授权如果仓库已归档Wiki 只读只能看不能改。3. 中文标题在地址栏变成一串编码现象新建中文页面后URL 显示%E4%B8%AD...仓库里文件名也是编码形式。 排查这是正常的 URL 编码不是错误页面内容和链接都有效。 解决无需处理若希望文件名可读页面名改用英文或连字符命名。4. 直接推送 Wiki 仓库被拒现象clone 后本地提交推送收到 rejected / out of date。 排查Web 端或其他人已先提交本地落后于远端。 解决先git pull --rebase再推送避免同一时间既在网页编辑又用 git 改。落地清单定一套页面命名规范统一用连字符分隔的短名如Install-Docker结构稳定新成员好找。提交说明写清楚改了什么历史是文档唯一的完整变更记录一句含糊的说明会让回溯变考古。把首页当目录用在Home页汇总各章节链接避免文档越写越散。重要仓库开启提交签名[signature]下把WIKI设为pubkey, twofa编辑身份可审计。用 clone 做备份Wiki 本质就是 Git 仓库定期克隆一份存到别处即可不依赖管理后台的导出功能。大文件不要放 WikiWiki 只适合 Markdown 文本图片和附件放代码仓库的 docs 目录或 Release 里。延伸阅读核心逻辑源码services/wiki/wiki.go页面增删改转提交、services/wiki/wiki_path.go页面名与文件名的转换规则页面路由与权限检查routers/web/repo/wiki.go完整配置模板custom/conf/app.example.ini搜索WIKI可定位所有相关项克隆完整源码阅读git clone https://gitcode.com/GitHub_Trending/gi/gitea【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考